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EXTENDING CIVICRM 



This section contains developer documentation for CiviCRM. It should be useful for developers 
wishing to extend CiviCRM and also for organizations who want to ensure that their developers 
are using best practices to extend CiviCRM. 

There are many different ways you can extend and customize CiviCRM, and this section takes 
you through them in order of simplest to most difficult. If you find that you cannot do 
something you're trying to do using the tools and techniques outlined in this section, please get 
in touch with the CiviCRM developers in the forums (http://forum.civicrm.org/) or on the IRC 
channel (#civicrm on irc.freenode.net) and let them know. Hacking on the core code should 
always be a last resort and done in consultation with the core team who will always be happy 
to help you find the best way to cover your use case. 

WHEN DO YOU NEED TO CODE? 

There are a lot of different options to customize CiviCRM to fit your specific needs. They are 
listed roughly in order of complexity: 

1. Change the configuration: (ok, this isn't coding but it is worth repeating) you can use 
custom fields, profiles, components and many existing Drupal modules andjoomla! 
extensions to customize CiviCRM without writing a line of code. This book covers many 
of these options in other sections, so make sure you've exhausted all of those 
possibilities before you dive into extending the code. 

2. Edit CSS: You can create a new Cascading Style Sheet (CSS) file and use it, for example, 
to adapt the style to your site or hide elements that don't make sense in your 
environment. Administer -> Configuration -> Global settings -> Resource URLs field 
"Custom CiviCRM CSS URL". 

3. Edit the templates: Useful to change the layout of forms, and to add more data or 
features via AJAX. Read about templating and APIs to know more. 

4. Implement hooks: Hooks are called at specific points in the code as users interact with 
CiviCRM and are useful, for example, when you want to change the default behavior 
when you create, update or delete an entity, create a new custom mail merge token, or 
to populate a custom field automatically based on your own business logic. 

5. Add custom searches or reports: Use these to fetch information and display it in a 
unique way. 

6. Extend your CMS: Create a Drupal module or Joomla! extension that integrates with 
CiviCRM. 

7. Override PHP files: In the same way that you can override templates, you can override 
any file in CiviCRM. If you have to modify core, it's much better to override files than to 
edit them. 

8. Write a new CiviCRM component or patch CiviCRM: Regardless of which path you 
take to extending and customizing CiviCRM, chances are that someone else would be 
interested in what you did. Share it with the community! If others start using your 
contribution, you're likely to get bug fixes, improvements, and documentation as a 
bonus. Let us know what you did in the forums or IRC channel (see above). 

Where possible use the documented APIs in your extensions, this will make them less likely to 
break when you upgrade CiviCRM. 

Before venturing into any development, we strongly suggest that you discuss what you want 
to do, and how you want to do it, with the community. We will help you find the simplest way 
to reach your goal and may be able to point you to others doing similar work. 

Please consider using the Academic Free License to open more opportunities to share your 
work. This also makes contributing your work back to the CiviCRM project very simple. 
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WHO IS CIVICRM? 



CiviCRM has a unique and diverse community centered around developing, using, and 
documenting the software. Our community includes the CiviCRM core team, people at the non- 
profits that use CiviCRM; consultants working with a number of non-profit organizations; 
programmers and developers, power users, volunteers and community organizers! We are also 
closely related to many other open source projects. 

Each member of the community interacts with CiviCRM in their own way, working to improve 
the software and how we organize ourselves. The strength of community comes from this 
diversity and the ease with which someone can join us, and means that we are constantly 
changing and improving, often in unexpected ways. 

Like all communities your membership is characterised by your interactions. If you treat 
others well, have some fun, and help others, then you can expect to enjoy being a member of 
the CiviCRM community. But if you are prone to complaining or don't use a respectful tone in 
communications, or if you see the community just as a resource and not as a collection of 
very kind, generous and clever people, then you are probably not going to get much of a 
response. Treat people well and you can find the CiviCRM community fun and rewarding. 

HISTORY 

CiviCRM started in 2004 by Dave Greenberg, Donald Lobo and Michal Mach. The founders had 
a lot of previous experience working with non-profit organizations and tools. The group was 
influenced very early by Zack Rosen and Neil Drumm, who convinced them to use Drupal as a 
fundamental cornerstone for CiviCRM. This decision has meant that the developers have been 
able to leverage a lot of the functionality that Drupal provides, freeing the team up to focus 
on building the features necessary to make a great CRM. 

In 2005 the first version of CiviCRM was released with two of the core modules in place: 
CiviMail and CiviContribute (you can read more about these later). 

Since those early days CiviCRM has built a large community of users and contributors (there 
are now over 8000 installed sites), the software has gone from strength to strength (there 
are now 8 core modules and additional third party components), and the core team has 
expanded to 8 members. There is also a large ecology of free software contributors around 
the project and high-profile non-profit organisations such as Wikipedia, Creative Commons, 
Mozilla, and Amnesty International use CiviCRM. 

ITS GOOD TO TALK 

CiviCRM is an open and learning community, and people are ready to hear your ideas. If you 
have a good idea, there's nothing to stop you carrying it out - but the best way to start, is to 
start talking about it. 

If you're not sure where to start, the best place is probably the community forum 
(http://forum.civicrm.org/) . Ask people what they think about your idea. There's a wealth of 
experience on the forum, and with a bit of luck, someone will have tried something similar 
before. CiviCRM people are a friendly bunch and their guiding philosophy is collaboration. 

Depending on your idea, you'll be directed to the next best place - maybe an article on the 
blog (http://civicrm.org/blog/) . a page on the wiki (http://wiki.civicrm.org/) , a teleconference or 
a meeting up with another community member in real life, yes that's right, REAL LIFE! 

BE THE CHANGE 



So you have a great idea. Now you need an equally great action plan to accompany this idea 
and then you'll need to implement it. Although the CiviCRM community is friendly and 
supportive and will like to be involved and updated about your project, you'll need to be the 
driver. How will you get the resources together for your project? How can you fit it in with 
your day job? Finding a way to simultaneously achieve your own objectives and benefiting the 
CiviCRM community is the best way of getting things done. 

AND FINALLY... 

If you're a CiviCRM user who has an ongoing relationship with a consultant, there's nothing to 
stop you from also being an active member of the community. The community really benefits 
from direct feedback from end users - your consultant is only one person or organization - by 
asking on the forums you're opening yourself up to help and input from the entire community. 
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REAL WORLD EXAMPLES 



CiviCRM is used by all shapes and sizes of organisations that are located all over the world. 
Some have no paid employees, while others might have several hundred. Their needs range 
from very simple to fairly complex. In this chapter, we will have a look at real world examples 
of how organizations are using CiviCRM. 

Throughout this chapter you will see references to CiviCRM features such as CiviEmail, 
CiviMember, CiviPledge, CiviCRM Profiles and others. These are all components of CiviCRM and 
we have included references to them so you can become familiar with the language of 
CiviCRM; however, it's not important to understand the finer detail of these features at this 
point. 

• Double the Volunteers: WWOOF UK 

• A Spectacular Performance: Wellington Circus Trust 

• Suffering Relieved: American Friends Service Committee 

• Activating the Community: Healthy Environment Alliance of Utah 

• A CRM Education: Schoolhouse Supplies 

• Growing Satisfaction: New York State Nursery Landscape Association 

• Campaigning for Efficiency: Green Party of Aotearoa New Zealand 

• Quest for Success: QuestBridge 

DOUBLE THE VOLUNTEERS 

WWOOF (World Wide Opportunities on Organic Farms) UK places volunteers on organic farms 
where they can learn about organic agriculture in exchange for food and accommodation. They 
list 400 farms in the UK and place approximately 3000 volunteers annually. Before starting 
with CiviCRM, they used a number of different offline systems to process and manage 
memberships. For example, people sent in paper application forms and volunteers were sent a 
printed directory of the farms. 

What They Did 

WWOOF UK implemented CiviMember on the Drupal CMS (Content Management System). An 
integrated payment processor allows people to sign-up online to become members, and to pay 
online using a credit card (or later by cheque or cash). CiviCRM Profiles are used to create an 
online searchable directory of contacts and, using Drupal's CiviMember Roles module, access to 
this directory is controlled by synchronising users with the membership database. 

Since they wanted to continue to make the system inclusive to people who didn't use the 
internet, WWOOF UK used the CiviCRM administrative interface to allow staff to manually 
process paper applications and, using CiviCRM's export functionality, to export data for a 
printed directory. 

The Results 

Simple online sign-up and instant access to the directory saw WWOOF UK double their 
membership income in the first month of implementing the new system! Staff are able to 
access the data from anywhere, which allows for much more flexible working practices and 
the ability to recruit more volunteers to help run the organisation. Membership administration 
time was reduced to zero for the majority of members that chose online access. 



Transferring all office systems to CiviCRM was a change management challenge! - and was 
more than they had anticipated. If they were to do it again, they would try split the process 
up, perhaps putting the directory online first and then switching to CiviCRM for online sign-up. 
They also underestimated the amount of training that was needed on the new system and 
would plan more time for testing and getting used to the system before 'going live'. 

A SPECTACULAR PERFORMANCE 

This example shows how clubs can use CiviCRM for summer 
Jt^^^fc J—,^ camps, regular classes and other events. 

^*,.i^ _r ~"^ "■« "i '■ - " 

^ W E I N L ON Wellington Circus Trust in Wellington, New Zealand is run entirely 
rU-S TRUST b y v °!unteers. They have a mailing list of 500-600 people and 
run blocks of classes in circus skills such as trapeze and hula 
hoop. They also host events. For safety reasons, the Trust needs to gather information about 
who to contact in the case of a student being injured. The Trust processes about 200 
enrolments a year. 

Prior to using CiviCRM, the Trust maintained a Microsoft Access database, but data entry was 
time-consuming, keeping information up-to-date was difficult and emailing the resulting contact 
information to the tutors on a regular basis was challenging. The treasurer wanted members 
to be able to maintain their own details and wanted the tutors and volunteers to be able to 
access member's contact details from anywhere. 

What They Did 

After some research, the Trust decided that CiviCRM could enable them do the things they 
needed to do, and as soon as the system was up and running they began to make the most 
of it. 

• They up online enrolment for circus skills classes with the CiviEvent component, and 
decided to pay a commission to a payment processing company so that credit cards 
could be used for online class payments. They also used CiviEvent to set limits on the 
number of students that could enroll in a given class. 

• To track emergency contact information, custom data fields were created and added to 
a profile that was used as a form for event registration. This information was then 
stored in CiviCRM. 

• They integrated CiviCRM with Drupal and set up user accounts for every contact in their 
database. The system's users were then instructed on how to use the Drupal 'reset my 
password' link to gain access to the system for the first time so that they could then 
update their own information. 

• CiviMail was implemented to contact tutors, volunteers and students. 

• Since the Trust applies for grants from funding bodies, they enabled the CiviGrant 
component. 

The Results 

Simply by implementing CiviCRM, tutors and volunteers can now access and manage 
information from anywhere in the world where they have internet connectivity. 

By implementing CiviEvent with a payment processor and custom data fields, people are able 
to enroll in and pay for classes online and provide the important emergency contact 
information at the same time. Allowing people to sign-up online has greatly reduced the 
amount of time spent on data entry. 

By integrating CiviCRM with Drupal and setting up user accounts, contacts are able to maintain 
and update their own information, greatly reducing administration time and improving the 
accuracy of the data. 



Implementing CiviMail has made it easy to email tutors, volunteers and students, and removed 
the administrative burden of manually updating the mailing list and contact information 
because contacts can do their own updates. The treasurer also found that it saved her from 
having hundreds of sent items in her email client, which used to be the result of using 
Microsoft Office mail merges to send out email newsletters. 

Prior to implementing CiviGrant, the Wellington Circus Trust had not been effective at tracking 
the status of grant applications. By using CiviGrant, they are now able to see at a glance what 
grant applications had been sent and the status of each application. 

All up, the Trust estimates that installing CiviCRM has saved hundreds of volunteer hours over 
the course of a year. 

After moving to CiviCRM, the Trust found that both contact management and class 
registration were easier. One issue they encountered was that some people were confused 
about having to reset their Drupal passwords. The Trust thinks that putting more effort into 
the way they explained this on their website would have helped. Another issue was the 
standard PayPal interface which was initially implemented as a payment processor; people 
found this difficult to use, and after six months the Trust invested in developing a payment 
processor more appropriate to New Zealand. 

They also learned that a cheap hosting provider is not always the best option: quite a bit of 
time was wasted before they switched from a free provider to one that costs them 
approximately $NZD20 per month and provides significantly better service. 



* 



American Friends 



SUFFERING RELIEVED! 

The American Friends Service Committee (AFSC) is a 

large, Quaker-based, peace and social justice 

organisation with over 400 employees. Worldwide, ^W^ Service CommitteB 

they run programmes that work to relieve and 

prevent suffering through both immediate aid and 

long-term development, and they seek to serve the 

needs of people on all sides of violent strife. 

Their main headquarters are located in Philadelphia, Pennsylvania. They have nine regional 
headquarters located throughout the United States, some 50 area offices also located in the 
USA, and numerous international field offices located in Africa, Asia, Europe, Latin America, 
the Caribbean and the Middle East. 

Lists of constituents are maintained by each office. The specific CRM system needs of each 
office vary but the general needs are: searching for constituents that meet certain criteria; 
sending emails, newsletters, postal mail and announcements; and collecting the contact 
information of people who sign online petitions and register for events online. 

Through a survey conducted by the AFSC Information Technology Department, it was revealed 
that AFSC staff were using a variety of systems to keep track of their constituents. It also 
became obvious that these systems were not working effectively: repositories of data were 
everywhere, contact information was duplicated, staff were having a hard time managing their 
contacts and the IT Department was unable to provide adequate support. 

The survey also found that staff members were frustrated with the systems they were using 
because they lacked the necessary functionality for them to effectively communicate and do 
outreach. Specifically: search capability was limited; there was no ability to send high-volume 
emails which meant that it was not possible to send newsletters or announcements; and there 
was no ability to collect information online. 

After investigating several database systems, the IT Department finally decided that, all things 
considered, CiviCRM might be the best fit for the AFSC. 



What They Did 

Initially, CiviCRM sites with CiviMail, managed by an external vendor, were established for 
offices in Los Angeles, Rhode Island, San Francisco and Seattle. Los Angeles also chose to use 
the CiviEvent component to track event registrations and the CiviMember component to track 
contact information of committee members. 

After implementation, an LA staff person discovered that certain functionality was missing 
from the CiviMember export component and this was preventing them from being able to 
compile a membership directory. AFSC talked to the CiviCRM Core development team and 
contracted them to add the missing functionality. This was a win-win situation: AFSC got the 
functionality they needed and because it was integrated back into the CiviCRM product, the 
entire CiviCRM community was able to benefit from the addition. An extra advantage for AFSC 
is that because the functionality became a standard part of CiviCRM they don't have to worry 
about compatibility with future upgrades. 

The Results 

The decision to have their sites hosted and managed by an external vendor turned out not to 
be a good one when the vendor ran into difficulties and was not responsive to issues or in 
providing the services that had been promised, such as timely updates for CiviCRM. Once the 
hosting issue was resolved, staff were able to take full advantage of the capabilities of 
CiviCRM and do all of the things that they had previously been unable to do. 

The Los Angeles office is in full swing, using CiviCRM as the main repository to track their 
constituents, board, committee members and volunteers. Their constituents are able to sign 
up for events and petitions online, and staff can send volume emails for newsletters and 
announcements. 

Getting rid of their old system and being able to send out a monthly newsletter was the main 
goal for the Colorado office, who came on board with CiviCRM a little later in the process. They 
are now able to identify newsletter subscribers and send the newsletter to them via CiviCRM. 
They couldn't be happier! 

The AFSC currently has nine CiviCRM sites and the IT Department is now recommending 
CiviCRM as the "database of choice" for all of its offices. Support from the CiviCRM community 
is excellent and CiviCRM itself is improving every day, as more and more functionality being 
added. AFSC staff are now able to access their data from any place that has internet access, 
run complex searches, manage online event registrations and send online newsletters and 
postal mailings. CiviCRM has enabled them to better manage their constituents. This makes 
their life easier and in turn, is of great benefit to AFSC. 

ACTIVATING THE COMMUNITY 




The Healthy Environment Alliance 

of Utah (HEAL) is a grassroots 

environmental organisation 

working to protect Utahns from 

nuclear and toxic waste. Before 

moving to CiviCRM, they were 

stuck with a Microsoft Access 

database. They may have called it 

a database, but in fact it was a 

glorified spreadsheet that did little to facilitate their day-to-day operations. The goal for the 

CiviCRM project was to move to a system that would centralise all of their information across 

their organisation including email lists, volunteer tracking, donor history and more. As an 

advocacy and community action organisation, effective engagement with their supporters and 

tracking the relationships they build with their constituency over time is critical to their 

mission. They needed a tool to support that mission. 



What They Did 

HEAL has been using CiviCRM since the early days of the software and CiviCRM is now the 
central place to track all donors, volunteers, legislators, foundations and contacts. They use 
CiviCRM for donor management, email communications, event management, volunteer 
tracking, and advocacy. 

• For advocacy purposes, constituents' legislative districts are monitored so that when 
issues arise that need action, HEAL can mobilise its members on a district-by-district 
basis. 

• The system tracks volunteers, the activities they participate in, and their interests. 

• HEAL holds large fundraising events with free admission where donations are solicited. 
CiviEvent handles all of the online registrations and collects data, such as guest names 
and interests. Invitations, reminders, and follow-up messages are sent via postal mail 
and the CiviMail component. 

• CiviContribute allows HEAL to run donor reports as well as accept online donations. 

The Results 

There is no question that CiviCRM streamlined and consolidated HEAL Utah's data 
management and saved the organisation valuable resources. It is interesting to note that over 
the last several years their advocacy campaigns have been more successful and their impact 
in their community more noticeable - perhaps in part because they have been able to redirect 
limited resources away from administration and into the real work. 

The biggest lesson that CiviCRM has brought to HEAL is to force them to always think about 
what role technology will play in their outreach and organising work. 
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A CRM EDUCATION 

Schoolhouse Supplies (SHS) is a Portland, Oregon, 
USA-based non-profit organisation which gathers 
and distributes school supplies to students and 

teachers SUPPLIES 

Prior to implementing CiviCRM, SHS used a combination of software programmes including 
Exceed, EROI, Constant Contact, Salesforce, Auction Pay (for online contributions) and, of 
course, hundreds of spreadsheets. In addition, SHS had a custom web application for managing 
its online store inventory and processing in-kind donations. 

What They Did 

By moving to CiviCRCM, SHS has centralised their operations and the management all their 
constituent data, and been able to unify and coordinate several of their core business 
processes. 

All data from each source has been migrated to CiviCRM Standalone (an installation that is not 
integrated with either Drupal or Joomla! CMS). CiviContact and CiviContribute have replaced 
Exceed and Auction Pay. CiviMail has replaced EROI and Constant Contact. Salesforce data was 
moved into CiviCRM and the custom e-commerce application it supported was integrated with 
CiviCRM. Lastly, the inventory and in-kind management system was integrated with CiviCRM. 
Spreadsheets have been imported. 

The Results 
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Each business process at SHS can now take advantage of their full constituent database and 
business activities are easily coordinated. More importantly, SHS is now in the process of 
taking manual business processes (such as volunteer coordination) and moving them to 
CiviCRM. New campaigns are now being planned and executed which would previously have 
been impossible or prohibitively expensive. 

GROWING SATISFACTION 

The New York State Nursery Landscape Association (NYSNLA) is 
a member-based association providing resources and advocacy 
support for nursery and landscape professionals throughout New 
York State. The organisation seeks to advance the interests of 
New York State's nursery and landscape businesses and 
professionals by promoting sound business practices, expanding 
state and local markets, and exercising leadership in the 
development of sustainable communities. 

Prior to migrating to CiviCRM the Association went through several iterations of member- 
management solutions, beginning with a series of spreadsheet documents and later moving to 
a Microsoft Access database. The move to CiviCRM was prompted by the desire to consolidate 
data, provide members real-time access to contact details, and to create a searchable 
member directory to website visitors who may be looking for a nursery or landscape 
professional. 

What They Did 

Working with a CiviCRM consultant, NYSNLA began the process of analysing the structure and 
content of their existing database and mapping the various functions to CiviCRM structures. 
They determined that they would use CiviMember, CiviEvent, CiviContribute, and CiviMail to 
address their core database needs, and would consider using CiviPledge at some point in the 
future for soliciting contributions to their associated non-profit, the Nurserymen's Foundation. 

One data area that required particular attention was their Certified Nursery Landscape 
Professional program (CNLP). CNLP is an intensive, on-going educational programme designed 
to increase the skills of garden and landscape employees. The programme was designed by 
members of the nursery and landscape industry with assistance from Cornell University. 
Interested individuals must apply to the programme and successfully pass a test. Certification 
lasts two years, after which time the individual must recertify. 

NYSNLA used CiviCRM's membership functionality to track the status of CNLPs. The ability to 
define a rolling-period membership and to gauge when they are nearing expiration perfectly 
met their management needs. The initial application process, which also must be carefully 
tracked, was handled through CiviEvent, as an application to the programme is essentially a 
registration to attend one of the bi-annual test events. 

The Association also took advantage of CiviCRM's open source platform to make some 
interface customisations that improved the way they view contact records. Because of the 
importance of the CNLP programme, they wanted to be able to look at all employees for a 
certain nursery/landscape company and quickly know if any of them are CNLPs or Lifetime 
CNLPs. They also needed to easily find out which employees are authorised to manage the 
company's records. 

The Results 
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The Association has worked hard to communicate to the public the importance of using a 
qualified landscape professional. Essential to this effort was the inclusion of a searchable 
member directory on their website. Using CiviCRM, they were able to create a search page 
that included geographic segmentation (the Association divides members into 8 regions state- 
wide) and a list of services provided by members (using CiviCRM's tags feature). The resulting 
search tool, because it is directly connected with their contact data, ensures website visitors 
are always looking at current information. The Association is also able to provide members 
direct access to their own contact details so they can update and maintain their list of 
services provided and other information. 

CAMPAIGNING FOR EFFICIENCY 




reen 



The Green Party has been the third largest party in 

New Zealand politics for most of the last decade, with 

strong roots in the Values Party (the world's first 

national Green party) of the early 1970s. They 

achieved parliamentary representation in 1996 and Green Party of Aotearoa New Zealand 

after the 2008 election had 9 Members of Parliament, 5,000 financial members and some 

50,000 contacts. The Party has more than 50 branches around the country and contest 

elections across all 67 electorates in the last election. 

Prior to adopting CiviCRM, the Party and its parliamentary units employed a range of systems 
for managing members, donations, contacts, campaigning, media and advocacy. 

The Green Party policy states: 

• Development of IT must be socially responsible and sustainable. 

• The use of free and open source software should be encouraged. 

What They Did 

CiviCRM was adopted by the Party in 2007 (version 1.7), with a switch to Drupal as a parallel 
project. This was inspired in part by work done by the Canadian Greens on developing a voter 
canvassing module for Drupal. A Party database was set up using CiviCRM and online 
donations, memberships and event registrations were instigated. 

The Greens have over 100 different issues that they generate media releases about. These 
were reconstructed as a check-box custom data field, and Smart Groups were built for each 
of these, for use when sending out media releases via CiviMail. 

The highly complex access control requirements of the party necessitated the development of 
an alternative approach to the use of ACLs (Access Control Lists) in order to provide a more 
easily managed, highly granular system. This approach has now been incorporated as a hook 
(something that can be utilised by developers to extend CiviCRM) into the core code. 

For the 2008 election campaign, a look-up function was developed so that when new contacts 
were added to the database, addresses were checked against a table containing the Electoral 
Roll, and links were created where matches were made. "Soft" matches were also recorded. 

The Results 

In the 2008 election campaign, the Party made extensive use of online fundraising and greatly 
exceeded previous online income. Membership renewal has been streamlined with more online 
renewals occurring. 

As of May 2009, the Party was still using CiviCRM v2.0 on Drupal 5 and therefore had not yet 
benefited from the many features that became available through the 2.1 and 2.2 releases. An 
upgrade was in progress at the time. 
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In a complex organisation such as the Green Party, training can be a limiting factor, as well as 
the need to nurture more in-house super-users. New features in CiviCRM have led to some 
rethinking about the Party's usage of custom data fields, particularly with regard to the use of 
CiviMail for media releases. New options for both nested groups and Drupal Organic Groups 
suggest that a more time effective approach may soon be possible. 

QUEST FOR SUCCESS 




QuestBridge is dedicated to helping bright, motivated low- 
income high school students get accepted to and able to pay for 
college. QuestBridge recruits high school juniors throughout the 
USA and invites them to fill out the QuestBridge application 
online. QuestBridge also partners with the USA's most selective colleges and universities with 
the aim to increase the socio-economic diversity of their student bodies. QuestBridge's college 
partners accept the QuestBridge application in lieu of their own admissions application. 



What They Did 

QuestBridge has built most of its business processes around CiviCRM. They wrote their online 
admission application using CiviCRM and extended it using the PHP scripting language. CiviCRM 
is used to store biographical and application information and communication histories about 
the students. 

The Results 



In 
the 




2008-9 school year, QuestBridge helped more than 1200 students get accepted and pay for 
college at its 25 partner schools. They accomplished their goals in a very efficient manner, in 
part thanks to their effective implementation of CiviCRM. QuestBridge is currently planning to 
upgrade to the latest version of CiviCRM in order to take full advantage of the new email 
features. 

If Questbridge were to start over they would have invested more in training on CiviCRM up- 
front. 
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WHAT IS CIVICRM? 



CiviCRM is a powerful, web-based contact relationship management (CRM) system. It allows 
an organisation to record and manage information about the various people and other 
organizations it deals with. CiviCRM is more than just an address book, it also allows you to 
track your interactions with people and organizations and to get them to engage with, and 
potentially give money to, your organization through your website. The information you gather 
is all stored in one place but you can access it from almost anywhere. 

CiviCRM focuses on the needs of non-profits. Most business CRMs are focused on managing 
commerce; CiviCRM emphasizes communicating with individuals, community engagement, 
managing contributions, and administering memberships. 

CiviCRM is open source, which means there are no license costs or user fees associated with 
downloading, installing or using the software. You may incur costs if you use a consultant to 
implement CiviCRM to meet your specific needs and you may incur website hosting charges. 

CiviCRM is web-based, which means it can be accessed by many users at the same time 
from different locations. It has been developed with the international community in mind, and 
translations and multi-language options are supported. 

A MODEL FOR UNDERSTANDING CRMS 

One way to understand what a CRM does is to think of your personal address book with 
enhanced capabilities. Imagine that every time you make a phone call to a given person, your 
address book automatically makes a note of it, together with brief description of the 
conversation. It can also decide whether to ask this person for a particular favor, based on 
whether she did this favor for you a week ago, and schedule a follow-up meeting following the 
call. After using this address book for a while, you could ask "What were my interactions with 
Ji Lao?" or "How many people helped me this month?" and it would give you the whole history. 

Now let's say you're organizing a dinner party and you want to invite all the people you've met 
during the previous year. Just write the invitation and tell your address book to send the 
email. You don't have to worry about anything else after this point (apart from preparing the 
dinner!). Your address book handles the RSVPs from all invited guests, together with 
information about who is vegetarian and who is not. It even lets you know two nights before 
the event how many people you can expect. 

It would be great to have such an "assistant", right? Organizations need one even more. It's 
hard to remember all of your meetings, phone calls and other forms of contact (especially 
over the long term), but the more you know about the people and organisations you interact 
with, the more successful your work will be. You'll be able to target your message to specific 
groups, because you know who will be interested in specific topics, and you'll be able to 
observe their reactions and adjust your next interaction, and continue to improve how you 
talk to different groups. 

CIVICRM AND CONTENT MANAGEMENT SYSTEMS 

CiviCRM works together with another common piece of software: a content management 
system (CMS). A CMS is a tool for creating and managing websites, and most websites these 
days are based on a CMS. 

Integration with a CMS offers a number of advantages for CiviCRM, most notably: 
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• visitors to your website can carry out many activities on their own, such as renewing 
their membership, signing up for events, requesting email updates, and donating money 

• you can share parts of your data, for example event information, with visitors to your 



website 

Drupal Content Management System - Content Types Screen 
Joomla! Content Management System - Control Panel screen 
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21. PLANNING WITH CIVIENGAGE 



CiviEngage packages a set of custom data groups and fields, reports, and other features for 
use in civic engagement and community organizing work. This chapter will describe the general 
concepts and planning needed to use CiviEngage effectively. 

WHAT YOU NEED TO KNOW 

The following are concepts, custom fields and values to keep in mind when preparing to use 
CiviEngage. 

Campaign Source Code 

Campaign Source Codes are descriptive values used to identify related activities, events, 
contributions, and memberships and map how these activities and transactions are linked 
together. Campaign Source Codes are also useful for identifying these sets of activities or 
transactions as part of a larger campaign, project, or program. 

For example, an organization is conducting a door knock canvass around a particular issue 
during a specific range of dates. The organization may want to use campaign source codes to 
link together the activities (where responses to door knock canvass questions are captured), 
the event (the door knock canvass campaign itself), and any contributions made during the 
canvass to be able to analyze the effectiveness of the campaign. 

Activity, Event, Contribution, Participant, and Membership records each contain a custom field 
to store a Campaign Source Code, that all share a common option list where Campaign Source 
Code values can be added and edited. 

Your organization can establish a standard method for creating new Campaign Source Codes 
so that the codes are consistent and easy to sort and understand at a glance. For example, 
you can specify that annual campaigns always include the year at the either the beginning or 
the end of the Campaign Source Code, not both, so that you don't wind up with "2009 Annual 
Campaign" and "Annual Campaign 2010." 

Issue Interests 

Issue Interests are issues that your organization works on or tracks. They are included in 
CiviEngage as a single option list shared across multiple contexts: 

• Grassroots Info: Issue Interests for individuals 

• Media Issue Interests for media contacts 

• Funder Issue Interests for funders 

• Grant Info: Funding Areas for organizations 

It is important to remember that despite appearing with different labels in these different 
contexts, you are still dealing with just one shared list of options. 

In planning to use CiviEngage you should come up with a list of distinct issues that are 
important to your organization and that you will want to utilize when tracking individuals' 
interest in your organization's work, the issues that your media contacts may be interested in 
covering, funders' general interests and the specific areas of work included in particular grants. 

Volunteer Interest 
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Volunteer interests are activities that your organization's volunteers can take on and 
participate in; you can indicate each individual's interest in participating in these ways. They 
are included in CiviEngage as an option list. In planning to use CiviEngage you should establish a 
list of your organization's current volunteer activities as well as any activities that you are 
planning to launch in the future. Some examples of volunteer interests are canvassing, phone 
banking, and tabling. 

Cleaning your Address Data 

Cleaning your address data means standardizing addresses to conform to the conventions 
defined by the United States Postal Service's Standards for Addresses. Standardizing how 
addresses are entered into CiviCRM will allow for more accurate search results when searching 
by address and is essential to generate accurate Walk List reports. CiviCRM will parse 
addresses based on the USPS standards. To find out more about how Address Parsing is 
handled and used in CiviCRM, refer to the Address Parsing chapter of this book. When adding 
or editing contacts you will be entering or editing address elements including street number, 
street name, and Apt/Unit/Suite number according to these standards. 

When planning to import pre-existing data into CiviCRM for use in CiviEngage it is essential that 
you plan to clean up address data before importing. 

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 
at http://pe.usps.com/text/pub28/welcome.htm . 

TRACKING CIVIC ENGAGEMENT AND CAMPAIGNS 

CiviEngage is designed to manage interactions with constituents around an organization's civic 
engagement and base-building work, such as door knock canvassing and phone banking. There 
are several concepts and details to consider when preparing for these types of campaigns. 

Working with Your Universe of Contacts 

In preparing for your campaign, you will need to identify the audiences you will be targeting for 
your door knock canvass or phone bank in CiviCRM. CiviCRM uses Smart Groups and regular 
Groups as the mechanisms to target specific groups of contacts. Here are a couple of 
examples of how you can use Smart Groups and regular Groups for targeting during your 
campaign: 

• You can use Smart Groups to identify contacts you want to target based on specific 
criteria, such as voter demographics, issue interests, primary language spoken, etc. 

• You can track voter demographics about your contacts using the custom data group 
called Voter Info 

• You can use Groups to identify contacts who subscribe to a particular newsletter or 
issue to do an email blast about your campaign. 

• You can then use these Smart Groups and regular Groups to generate your walk list or 
phone bank list. 

Learn more about working with Smart Groups and regular Groups in the "Tags and Groups" 
chapter of this book. 

Preparing a Campaign Event 

To prepare a campaign event in CiviCRM, there are several setup items you may want to 
consider: 
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• Define a specific Campaign Source Code for your event. This Campaign Source Code will 
be used for the event and the activity which holds the individual responses gathered 
during the door knock canvass or phone bank campaign. 

• When you set up your event with the Event Type set to "Campaign" you can record 
the questions being asked during the campaign in the Event Campaign Details area. 

• Decide how you want to identify participants in the campaign event. Maybe you only 
want to identify the staff and volunteers who will be involved in conducting the door 
knock canvass or phone bank. Maybe you'll want to add the targeted contacts as 
participants. Activities will be used to record the responses of each individual contacted 
during the campaign as well as the campaign source code related to the campaign, so it 
may not be necessary to add these contacts to the event. In either case, it is 
recommended to also record the Campaign Source Code in the participant's record in 
the Participant Info area. 

• When capturing responses from each individual during the campaign, consider how you 
plan on getting the data back into CiviCRM. If the plan is to enter data one contact at a 
time, which may make sense for phone banking, you will need to record the response in 
the individual's activity record, with the Activity Type of "Door Knock" or "Phone" in 
the Walk List Responses or Call List Responses area. But if you plan on entering 
batches of data at a time, then you will need to plan to import the responses using the 
Import Activities function. 

Working with Voter History 

When using CiviEngage, plan how you will manage voter history and other voter information 
collected during a voter engagement or electoral cycle. Many organizations have access to a 
voter file from which they manage all their voter engagement work outside of CiviCRM. Once 
the voter engagement or electoral campaign is over and voter information is updated with 
who voted and other demographics, organizations most often will only want to keep 
information on the actual contacts they made during the campaign. In this case, only those 
selected records from the voter file and additional voter information, such as responses to 
specific electoral campaign questions, will be imported and maintained in CiviCRM. These voter 
records then become contacts that organizers will continue to engage and target with base- 
building efforts. 

If you wish to collect voter contacts with their demographics, history, and additional 
information, first import voter contacts (with their contact information and demographics) into 
the Voter Info custom group. Then import additional information as Activities, such as 
responses to electoral campaign canvass questions. 

MOBILIZING INDIVIDUALS TO ATTEND AN EVENT 

The Participant Info custom data group that comes with CiviEngage contains fields that hold 
information about prospective event participants, including a history of interactions between 
your organization and prospective participants. Use this information (such as needs for 
childcare or rides) to bring these individuals to your events. Tracking the history of your 
organization's contact with individuals around events such as an annual membership meeting, 
a direct action, or leadership training can help you to understand the effectiveness of your 
outreach methods and determine how committed or engaged an individual is based on if the 
individual actually attends events after multiple contacts. 

This feature is mostly useful for organizers or staff who have a list of individuals they are 
recruiting to attend an event through multiple phone calls or face-to-face meetings. The 
following CiviCRM tasks could be used to mobilize individuals: 
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1. Conduct a basic or advanced search or use Groups and Smart Groups to create a list of 
the contacts you want to mobilize or invite to the event. 

2. From the search results or Group Contacts screen, you can add the list of contacts to 
the event by selecting Add Contacts to Events from the Actions list. To find out more 
about how to add contacts to events, refer to the Managing Participants chapter in the 
Events section in this book. 

3. Once you add the contacts to the event, you can enter participant information or 
responses from multiple interactions in the Participant Info area in a contact's 
participant record. You can either enter information for one participant by editing the 
participant record itself, or you can add information for a list of participants at one time. 
For example, if you plan to call through your list by viewing the participant list from the 
event listing, you could use Batch Update Participants Via Profile and select one of 
the following custom profiles provided by CiviEngage: 

• Update Event Invite Responses - to record responses from multiple contacts with the 
participant. 

• Update Participant Info - to record general information about participants, such as if 
they need childcare or rides to the event. 

TRACKING FUNDERS AND FOUNDATIONS 

You can track information about and due dates for grant proposals, letters of inquiries, and 
reports for funders by adding an activity related to the funder's contact record and choosing 
from the Proposal, Letter of Inquiry, or Report activity types. 

You can also tailor information about an individual funder, such as their funding areas and 
issue interests, using the Funder Info custom group. In order to view the Funder Info tab, you 
will need to use the Individual sub-contact type, Funder, when you create a new contact that 
is identified as a funder. 

You can tailor information about a foundation (organization record), such as their program 
areas for funding, using the Grant Info custom group. 

TRACKING MEDIA CONTACTS 

As part of civic engagement and community organizing work, it can be useful to track 
information about your media contacts in CiviCRM, especially if you want to know which media 
contacts or outlets are interested in your organization's issues, or have written articles about 
your work, or for identifying who to contact when you want to publicize the work the 
organization is undertaking. 

You can tailor information about an individual media contact, such as their media type (e.g., 
TV, Newspaper, Photographer, etc.), issue interests and beat using the Media Info - Ind 
custom group. Use the Individual sub-contact type, Media Contact, when you create a new 
contact for a media contact. You can then view and edit the Media Info - Ind tab. 

You can also tailor information about a media outlet (organization) such as their media type 
(e.g., TV, Newspaper, Magazine, etc.) using the Media Info - Org custom group. As with the 
individual media person, use the Organization sub-contact type, Media Outlet, when you 
create a new contact for a media outlet. You can then view and edit the Media Info - Org 
tab. 

TRACKING ELECTED OFFICIALS 

Identifying and collecting information about your elected officials could be useful for your 
community organizing and civic engagement work. You may want to know who is an elected 
official in a specific district, or who to contact on their staff, such as the scheduler, or 
spokesperson. 
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You can tailor information about an individual elected official, such as their elected position 
(e.g., city council, Senate, etc.) and their role using the Elected Info custom group. Use the 
Individual sub-contact type, Elected Official, when you create a new contact for an elected 
official. You can then view and edit the Elected Info tab. Remember that staffers, schedulers, 
or spokespeople for an elected official can be entered as the Elected Official subtype. 

REPORTING AND ANALYSIS 

There are two reports packaged with CiviEngage: Walk List and Phonebank List. In addition, 
the Activity Report is enhanced to filter custom activity fields such as those associated with 
the custom group Call List Responses and Walk List Responses. 

The Walk List report allows you to view, print, or export an individual's contact information 
and demographics such as Member Type, Sex, Age, Party Registration, Voter history, along 
with response codes and notes where a volunteer can collect responses during a door knock 
canvass. 

The Phonebank List report is similar to the Walk List report except that this report is used 
exclusively during a phonebank and contain response codes pertaining to phone responses. 

The Walk List and Phonebank List reports are used to collect information during a campaign to 
later be imported or batch entered back into CiviCRM. 

The Activity Report is enhanced to allow you to search, view, print, or export for specific 
responses from a door knock canvass or phonebank campaign. Use this report not only to 
analyze the effectiveness of your campaign (e.g., how many people you contacted and 
collected responses from) but also to analyze responses from your constituency around an 
issue, or to determine whether individuals may become more involved with your 
organization. 

Disabling vs. Deleting Custom Data 

If you decide you don't need to use or view particular custom groups, fields, or values, we 
strongly recommend that you disable the group, field, or value rather than delete them. The 
Walk List and Phonebank List reports rely on these fields, so deleting certain custom data 
could potentially "break" the reports. 
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IS CIVICRM FOR YOU? 



This chapter will help you to decide whether CiviCRM is the right tool for you organisation. 

CiviCRM is powerful software and has the potential to help your organisation reach its goals - 
but it won't be the right choice for every organisation. Here are some ways that you can find 
out whether CiviCRM is right for your organisation: 

• read the book Understanding CiviCRM (you might be doing that right now) 

• play with a demonstration site 

• install a test database 

• talk to others who use CiviCRM 

• talk to a CiviCRM consultant. 

DEMONSTRATION SITES 

CiviCRM hosts two demo sites - one for each of the two supported Content Management 
Systems (CMS) - Drupal and Joomla!. The demo sites present a working copy of the latest 
stable version of CiviCRM with sample data. You can use them to play around with CiviCRM 
but be aware that they are publicly viewable so you shouldn't enter personal data. 

The demos are available at: 

• Joomla! Demo: http://joomla.demo.civicrm.org/ 

• Drupal Demo: http://drupal.demo.civicrm.org/ 

Other people are likely playing on the demo sites at the same time as you, so they may be 
configured strangely, missing functionality or appear in different languages. 

The demos have some limitations - you can't send emails from them, you can't set 
permissions for Drupal users or do a full exploration of online payment options. 

If you are having trouble working on a demo site, contact the CiviCRM core team via the 
forum or IRC. If you want a more controlled evironment for exploring CiviCRM, install your 
own test site. 

TEST INSTALLATIONS 

If you have technical skills or are feeling adventurous, you can download and set up a local 
version of CiviCRM, that is a version that is stored on your local computer rather than on a 
server on the internet. You'll still access it through a browser, but it will only be visible on your 
computer. The advantage of a test installation is that you can configure CiviCRM in the way 
that you want to use it, and experiment with your data. 

Up-to-date information for installations (including troubleshooting tips) is maintained at 
http://wiki.civicrm.org/confluence/display/CRMDOC/lnsta Ha tion+and+Upgrades . 

TALKING TO OTHERS WHO USE CIVICRM 

If you know of another organisation that uses CiviCRM, talk to them about their experience. 
Obviously the more similar they are to your organisation, the better. If you don't know anyone 
that is using CiviCRM, have a look on the CiviCRM forums, at case studies on the wiki, or try 
your local non-profit technology mailing list. 
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The CiviCRM forums (http://forum.civicrm.org) have a few boards for people who are new to 
CiviCRM, such as "Pre-installation Questions" 

(http://forum.civicrm.org/index.php/board, 5.0. html) . Remember that the forums are staffed by 
mainly by volunteers so you will get a better response if you spend some time formulating an 
easily answerable question. You can also search the forums and browse for questions that 
others have asked. If you wish you ask questions or contribute to the discussions you must 
register first. 

TALKING TO CIVICRM CONSULTANTS 

Another option to help you understand CiviCRM is to make use of a professional. The CiviCRM 
website lists professional vendors and consultants that can walk you through CiviCRM 
(http://civicrm.org/professional) , and there are many others; you may find a local website 
company who has experience with CiviCRM. Consider hiring a consultant for a day to discuss 
with you how CiviCRM could help your organisation. 
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IDENTIFYING YOUR NEEDS 



This chapter covers some basic strategies for identifying your organisational needs, and how 
they could be met by CiviCRM. It doesn't go into detail about CiviCRM functionality or how 
CiviCRM stores data (you will find that in other chapters). Instead, we encourage you to first 
take a step back and think about your organisation. 

YOUR ORGANISATIONAL GOALS AND PRACTICES 

For now, forget about technology and focus on your organisational goals and processes. Here's 
a list of questions to start you off: 

• What are the high level goals of your organisation? 

• What tasks are staff involved with on a day to day basis? 

• What activities do staff carry out with your contacts (members, constituents, clients)? 

• What different teams and roles exist within your organisation? 

• What services do you provide to your contacts? 

• How do you communicate with your with contacts? (include information flows into and 
out of your organisation) 

• What happens when you receive someone's contact information? 

• In what ways does money flow in and out of your organisation? 

• Does your organisation have a membership structure? 

UNDERSTAND YOUR "CONTACT RELATIONS" 

The CRM in CiviCRM stands for Contact Relationship Management. By contact, we mean an 
individual, household or organisation that your organisation has contact with (you may call 
them members, constituents, clients or some other term). 

Many organisations make the mistake of not thinking about who their contacts actually are. 
Spend some time identifying all the people involved with your organisation. What different 
types of people do you interact with, and how do they differ from each other? The better you 
understand them and their interactions with your organisation, the better you can model them 
in CiviCRM. Anecdotal or systematic feedback from your contacts may be useful here. 

TAKE ADVANTAGE OF INSTITUTIONAL KNOWLEDGE 

In thinking about your contacts and their interactions with your organisation, talk to your co- 
workers, including those who have been around the longest and those who have just joined. 
Talk to as many people as possible to get a complete picture of their interactions with all 
kinds of contacts. 

As well as talking to people, look at your organisation's data repositories: your databases, 
spreadsheets, file servers, address books, and any existing stored information you may have 
that can help you understand your contacts are and how they interact with your organisation. 

MAP YOUR NEEDS TO CIVICRM 

CiviCRM has been designed to be flexible and adaptable, based on feedback from many 
different non-profits, but it may not map exactly to the ways that your organisation currently 
works. Doing things the CiviCRM way could mean adapting your workflow and adopting best 
practice in non-profit technology. Be pragmatic and flexible and consider whether your current 
working practices need to change. 
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It's worth remembering that CiviCRM offers many opportunities to interact with your contacts 
in ways that you have not previously had. Taking advantage of these new possibilities can lead 
to positive changes and improvements. 
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6. 



PROJECT MANAGEMENT 



This chapter outlines the parts that typically make up a CiviCRM project and should be read by 
people about to embark on a CiviCRM project. Some of this information may be obvious to 
experienced project managers. A comprehensive guide to project management is beyond the 
scope of one chapter but we have outlined things that are typically encountered in a CiviCRM 
project and provided pointers on some things to watch out for. 

First, some pop philosophy courtesy of Cynthia Tarasco: 

"Life is a series of making decisions. Some decisions are easy because they do not require a 
substantial investment of time or money. Deciding which flavor ice cream to buy fits into this 
category: if you get vanilla today you can always get chocolate tomorrow. Other decisions are 
much more difficult because they require substantial investments of resources, and you will be 
living with your choice for the foreseeable future. Adopting a new CRM fits into this category, 
so planning and project management are vital". 

When you start out on a new CiviCRM project you should spend time thinking about: 

• the people who will be involved in the project 

• how you will approach the initial development 

• what ongoing support you will need 

• the costs associated with hosting and your IT infrastructure 

• training and documentation 

• change management 

PEOPLE AND THE PROJECT TEAM 

Including a wide range of people that represent the different parts of your organisation will 
help with delivery of your project. A mixture of management and day-to-day staff helps the 
team to keep an eye on the big picture as well as ensure that the project is ultimatley useful 
to frontline staff. 

You'll be exploring new territory with your CiviCRM installation and this can sometimes be 
stressful. It might be helpful to share project management of the project with others who can 
give you a different perspective and moral support when you need it! 

Managing a CiviCRM project will require a major time investment from people within your 
organisation, even if you employ an external consultant. Organisations often under-estimate 
the amount of time that will be required from their staff in implementing an IT project - such 
as training, modifying existing processes and providing new or updated information to relevant 
people. It's not something that can be tacked on to the end of an already busy schedule and 
this should be taken into consideration. 

DEVELOPMENT 

It often makes sense to break development up into smaller more manageable sections, which 
can be implemented in discrete stages or iterations. A common first phase of development is 
to choose something simple to implement in CiviCRM, or specific functionality for a team who 
can then act as CiviCRM evangelists within the organisation. 

Implementing in stages allows staff to get used to changes gradually without feeling 
overwhelmed, and gives the developer or implementor the ability to be responsive to feedback 
from users during the development process. 
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Another reason that people choose to develop iteratively is that it very hard for users to 
correctly or fully articulate their requirements at the start of the project. Giving users hands- 
on experience of an early version of the system helps them understand how it works and 
what is possible. They can then provide valuable feedback and might articulate requirements 
that they haven't thought of previously. 

Implementing your CMS (Drupal or Joomla!) either before or after implementing CiviCRM is 
another convenient way to split up a CiviCRM project. As well as the normal advantages of 
breaking up the development into manageable chunks, this helps staff understand the 
important differences between a CMS and a CRM. 

Pilot projects 

Pilots help to reduce risk during a project implementation. For example, rather than moving 
your organisation's entire event management infrastructure to CiviCRM, run one pilot event 
using CiviCRM and evaluate it. You can then incorporate the learning back into the 
development process. 

ONGOING SUPPORT AND DEVELOPMENT 

It is a mistake to think about a CiviCRM project as a one-off development that will meet the 
needs of your organisation for the foreseeable future. Organisations constantly change and 
evolve and your CRM should evolve with you, otherwise it will eventually become out-of-sync 
with the organisation. 

Once you have been using CiviCRM for a while and staff are comfortable with it, you will likely 
want to take advantage of other functionality. Each improvement or new piece of functionality 
that you decide to implement in CiviCRM will take resources, so you'll need to plan for these. 

Even if your organisational needs don't change, there are ongoing support implications, 
including: 

• keeping your site up-to-date with security patches 

• upgrading to the latest version of CiviCRM (not necessary, but CiviCRM is improving all 
the time and it your users will thank you for the improved usability and functionality 
each time you upgrade) 

• upgrading the CMS (Drupal or Joomla!) 

• hosting 

TRAINING 

Training is a significant aspect of most CiviCRM projects. Your training could take many shapes 
and sizes depending on your users, but it often makes sense to spend resources on formal 
and reusable training resources (user guides, lesson plans and so on). 

CiviCRM's range of functionality can be overwhelming at first (especially to the less technically- 
minded). Remember that staff who were not involved in the project's early stages will need to 
have concepts explained clearly to them - things that are obvious to you may be quite foreign 
to others. 

Trying to cover everything in one training session probably won't be effective; your staff will 
need time to digest the new ideas. Instead, hold smaller training sessions that introduce 
concepts and specific functionality, followed by periods of testing, piloting and feedback. Tailor 
your training for your audience: not everyone needs to sit through a two-hour training session 
on how to manage events if there is a single person responsible for event management and 
planning. And where possible, involve staff in training other staff members as this increases 
the sense of ownership and helps to embed learning. 
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Training is also ongoing. New staff will need to be trained, users familiar with the system can 
benefit from learning about more advanced topics, and staff will need further training when 
there are significant upgrades or new functionality added. If you plan to use CiviCRM for any 
large or mission-critical events, allow adequate time for additional staff training and testing. 

HOSTING AND INFRASTRUCTURE 

Hosting is a key aspect of any CiviCRM project. You will need to provide for maintenance of 
the server on which CiviCRM is stored, and have someone available to fix problems that 
inevitably occur from time to time. If your site needs to be accessible 24 hours a day, you 
should have a support agreement with your ISP that covers this. Ensure that your budget is 
sufficient for appropriate hossting, and that effective backup procedures and policies are in 
place. 

Keep in mind that in the hosting provider world, you get what you pay for. In many cases, 
cheap hosting providers keep their prices down by limiting the services or flexibility they 
provide. CiviCRM doesn't work well on cheap hosting, and under-budgetting for hosting may 
lead to other problems. Similarly, make sure that the computers your staff are using are 
powerful enough to provide a good experience with CiviCRM. 

CHANGE MANAGEMENT 

Introducing a new (or the first) CRM will cause changes in work flow and processes at your 
organisation. These changes may be "political", practical or technical. Either way, a lot of 
change at the same time can be difficult and stressful. 

To mitigate this, give staff time to accept and support each change so that they share in 
ownership of the new system rather than feeling as if something has been forced on them. 
Focus on simple tasks at the beginning of deployment and introduce more difficult tasks as 
staff understanding of the system grows. Show staff how the new system will make their 
work easier and where their feedback has been incorporated. 

Good planning can minimise the risks around change, but it is important to be flexible within 
your plan; unforeseen things often occur, and a rigid plan could prevent you from reaching the 
best solution. 



28 



CONFIGURATION 

7. HOW DATA IS ORGANISED 

8. EXTENDING CORE DATA 

9. USING CIVICRM PROFILE 

10. INSTALLATION 



29 



7 



HOW DATA IS ORGANISED 



This chapter covers the main building blocks that CiviCRM uses to store data, and describes 
their intended usage. It is recommended reading for working out how you should organise your 
data in CiviCRM. 

A successful CiviCRM installation depends on having your data stored in the right place. This 
chapter goes through all of the places that you can store data and helps you to understand 
why you would store data in one place and not another. 

Equally important to understanding the different building blocks presented below is 
understanding how they can be extended using custom data (described in the next chapter). 

CONTACTS 

Contacts are the main building block of CiviCRM. There are three types of core contacts in a 
standard installation: 

• Individuals 

• Organisations 

• Households. 

Contacts hold contact information, including: 

• name, nickname, greeting, title 

• website, email addresses, phone numbers, IM account name 

• addresses 

• communication preferences (which method do they prefer being contacted by, and which 
methods do they not want to be contacted by). 



All of the other building blocks of CiviCRM such as relationships, contributions and groups are 
connected to contacts in some way, so you can see events that a contact has attended, or 
what contributions they have made. 

You can define further contact types to suit your needs, for example "students", "farms" or 
"churches". Each contact type you define is based on one of the three core contact types. 
For example, students would based on individuals, and farms could be based on organisations, 
or perhaps on households, depending on your situation. 

A contact can be only one contact type. For example, they can't be a student and a teacher 
(but contact types are not the only way to differentiate your contacts). 

All users of your content management system are also stored in CiviCRM as individuals. Their 
contact record in CiviCRM is linked to their user record in the CMS (Drupal or Joomla!). Note 
that only individuals can be linked to user records in your CMS. Organisation and household 
records in CiviCRM cannot be directly linked to user records in your CMS. 

RELATIONSHIPS 

Relationships are a way to connect two contacts to each other. Two out-of-the-box 
relationship types in CiviCRM are the "employer - employee" and the "parent - child" 
relationship types. 
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There are always two ways to describe a relationship in CiviCRM: one describes the 
relationship of A to B, and the other of B to A. For example, Adam is Bernard's son and 
Bernard is Adam's father. Sometimes both descriptions with be the same: Charlie is Diane's 
friend and Diane is Charlies' friend. 

CiviCRM comes with a number of relationship types in the standard installation. You can define 
further relationship types to meet your needs, for example you might define a relationship 
type of "vicar - church". 

It may be helpful to compare relationships to groups: relationships connect two contacts, while 
groups contain two or more contacts who have something in common. 

GROUPS 

Groups are useful to identify two or more contacts with something in common. For example, 
the advisory board of your organisation could be modelled as a group. 

Groups are often used as mailing lists. For example, you could create a group containing all 
your newsletter subscribers, then use the group to send an email newsletter. 

A group can be the "child" of a "parent" group. When a group is a parent, selecting the 
contacts in that group will also select contacts that are in the child group. 

For some groups, such as your advisory board, you might want to capture other types of 
relationships than a simple "belong to" (eg. president, vice-president, member, substitute). 
Instead of creating a group, you might want to create a new type, "board", and a contact, 
"advisory board", then add the members of the group as relationships to that contact. For 
mailing purposes, you might want to create a smart group with all the related individuals (no 
matter the type of relationship) of that board. 

Groups are also used in many other situations. For example, a search can be saved as a group 
(or a smart group) and groups can be used to provide permissioning. To find out more about 
groups and how they are used, read the chapter on groups and tags. 

TAGS 

Tags are in many ways similar to groups, but as well as being used to identify contacts they 
can also be applied to activities and cases that have something in common. To find out more 
about tags, and how they are different from groups, read the chapter on groups and tags. 

ACTIVITIES 

Activities is a key concept in CiviCRM. Activities track interactions between the organisation 
and its clients or contacts at a specific point in time. All of CiviCRM's components make 
extensive use of activities, such as to record contributions, event attendances, membership 
subscriptions, and emails. 

You can create additional activity types to define specific activities that your organisation 
carries out, for example, "completed annual survey". 

Activities have the following characteristics (most of these should be filled in for each activity 
and those in bold on the form are required): 

• time: activities always happen at a certain point in time 

• status: is the activity scheduled, completed, cancelled, etc. 

• added by: the person who added this activity, or the contact if they carried out the 
activity themselves via the website 

• assigned to: the person (usually within your organisation) that carried out (or will carry 
out) the activity (this is often the same as the person who added the activity) 

• with contact(s): the contacts in your database that are the subject of the activity. 
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Compare activities to groups. Which would you use to record that you have sent a 
membership pack to a contact? You could add all contacts that have received a membership 
pack to a group "received membership pack", but it would probably be better to record this as 
an activity. That way, you can record when the membership pack was sent, who sent it, any 
notes about what the person requested, and so on. You could also use the activity to schedule 
sending membership packs by setting the status to scheduled. 

CONTRIBUTIONS 

Contributions are a type of activity, and a fundamental concept of CiviCRM. Contributions are 
used whenever there is a financial element to an interaction. A contribution will be created for 
each donation or campaign contribution, for paid events and for membership fees. 

CiviCRM comes with several predefined contribution types (including donations, campaign 
contributions, membership fees and event fees). You can define additional types to meet your 
needs. 

Contributions have different statuses which reflect the process of receiving a contribution. 
Some of these statuses are are set automatically by payment processors. 

For more information, see the section on CiviContribute. 

MEMBERSHIPS AND MEMBERSHIP TYPES 

Memberships are another type of activity. As well as the usual activity fields, they contain 
extra fields used for tracking memberships, such as start and end dates. 

CiviCRM allows you to define different membership types with fees, start and end dates, and 
other settings. You can define the types that meet your organisation's needs. 

Memberships can be renewed. When this is done, the start and end date will move on by the 
specific time period but the join date will remain the same (i.e. the same as the first 
membership start date). 

If the membership has a fee associated with it, this will be recorded as a contribution and 
linked to the membership. 

For more information see the section on CiviMember. 

EVENTS AND EVENT ATTENDANCES 

CiviCRM has a building block for events which contains fields to add events and give these 
events, times, locations, fees and other information. 

When a contact registers for an event, an participant record is created linking the contact to 
the event. A participant record is a type of activity. 

For more information see the section on CiviEvent. 

CASES 

Cases are a way to logically connect a series of activities. You can define different case types 
and associate a predefined series of activities with them. When you create a new case, you 
typically create a series of scheduled activities that need to be completed as part of that 
case. As the case progresses, you can record new activities, or series of activities, as part of 
the case. 

For more information see the section on CiviCase. 

32 



8 



EXTENDING CORE DATA 



This chapter explains how you can extend the core building blocks (or objects) in CiviCRM by 
adding custom data fields that represent the data that you want to collect. For example you 
can extend organisations with a set of check boxes about the clients that they serve. 

You can either extend custom data for all of a specific object, or for just certain types of that 
object. For example, you might have a custom fields for subjects that only apply to the 
contact type students. 

Custom data fields are stored in CiviCRM in custom data sets. The workflow when creating 
custom data is to first create a custom data set that applies to a particular object, and add 
custom data fields to this set. 

CUSTOM DATA FIELDS 

Custom data fields come in many different flavours and each flavour is designed for a different 
purpose. You'll hopefully be familiar with these different field types from seeing them on 
different websites. Experiment with creating different field types to get an idea of how they 
behave. 
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• Alphanumeric (i.e. text and number fields) can be of the following type: 

o Text - a simple text form field 

o Select - a drop-down box which limits choice to one selection 

o Radio - a list of options where you can make one selection and all options are 

visible on the screen. Compare this to Select and note that there is a pre-built 

Yes/No data type 
o Checkbox - a list of options with checkboxes that allows multiple selections 
o Multi-select - list of options in a single box. You can select multiple selections 

using Control-Click 
o Advanced Multi-select - two lists side by side in which items can be moved from 

one to the other 
o Autocomplete select - an Ajax auto-complete widget 

• Integer, i.e. a whole number. 

o this can be implemented as a text box, or as a select or radio (see above) 

• Number - i.e. any number including decimals like 3.142 

o this can be implemented as a text box, or as a select or radio (see above) 

• Money - similar to number but this will be treated according to the local currency as 
configured in CiviCRM's admin pages 

o this can be implemented as a text box, or as a select or radio (see above) 

• Note - a longer text box which allows multiple lines. Notes come in two flavours: 

o plain 

o rich text (i.e. a WYSIWYG editor which allows html) 

• Date - with a fancy dropdown. Can include hours and minutes. 

• Yes or No - as radio buttons 

• State/Province - selection options as defined in global setting. Either as select dropdown 
or multi-select 

• Country - selection options as defined in global setting. Either as select dropdown or 
multi-select 

• File - browse to select and upload file) 

• Link - active hyperlink) 

• Contact Reference - and Ajax auto-complete widget for an existing CiviCRM contact 

When choosing a data type, think carefully about how you want to display and use the 
information as different options have implications for how they can be used. For example, 
checkboxes enable you to use OR as well as AND searches in Advanced Search, whereas 
multi-select will not 

As well as selecting the field type, there are a few other setting to work through. 



34 



Custom Data Field 
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Field Label 

The name used in screen displays and when you export data. When using fields in a profile you 
can overwrite the Field Label. So you can choose names that are suitable for administrators 
and give more user friendly names when exposing them in profiles. 

Order 

As the name would suggest, the order field controls the order in which the fields appear. You 
may assign the order in the field edit form, or use the up/down icons on the main field listing 
table to adjust the field presentation. By default, new fields appear at the bottom of the field 
list within a set. 

Default Value 

Where applicable, you may designate a default value for a field. Note the format required for 
date fields (YYYY-MM-DD). 

Field Help 

In most cases, a field's name is self-explanatory in describing the purpose of the field. But in 
those cases where there is some ambiguity, or where you wish to help regulate how a certain 
field is used, you may enter help text. The help text appears below the form field. Note that 
the text identified here appears in all uses of the field in administration pages and is inserted 
as the default help text when fields are assigned to a profile. When used in a profile, the help 
text may be removed or changed without impact on the original custom field definition. 

Required 

As you begin defining each of your custom fields, you will undoubtedly come across some fields 
that you wish to designate as a required field. By selecting this option, you ensure that 
whoever is completing the form must provide a value for this field before submitting the form. 
Failure to do so will result in an error message directing the person to complete the required 
field(s). 
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Note that you might want to have a field that is mandatory only in the context of a specific 
profile. You have the possibility to request the field to be set only in the profile, but let the 
option to have it empty in general. Read the chapter about profiles to learn more about it. 

Is this field searchable 

CiviCRM's advanced search page is a powerful tool for running complex queries on your 
records. The tool includes a custom field panel which displays custom fields configured to be 
searchable, as defined in this option. As with other areas of CiviCRM, it is worth thinking 
through how you will use the particular field you are defining. 

While you may be tempted to simply mark every field as searchable, doing so may 
unnecessarily clutter the advanced search custom field panel, when in fact certain fields will 
likely never be used in that way. You may toggle this option on or off at any time, so don't be 
overly concerned about arriving at a final decision during this initial field-definition stage. 

Active 

The "active" option determines if the field is disabled or enabled within the CiviCRM interface. 
Disabling a field does not remove the data from the system — it simply hides the field from the 
contact interface. While this option may seem rather mundane and obvious, it can perform 
very valuable functions when managing your data, especially if you are migrating from an 
existing database system. 

For example, you may have certain fields in your existing database that you would like to 
transfer to the new system for historical data keeping purposes but plan to then deprecate or 
migrate to a new data structure in CiviCRM. Suppose you are importing membership records 
from an MS Access database. Each record in Access has a unique ID (key) field, which has no 
direct benefit in CiviCRM. Rather than ignoring it altogether, you could create a custom field to 
hold the value, import the records, and then disable (un-activate) the field, thereby hiding it 
from view and minimizing the interface clutter. 

Though not visible to users, the field value is stored in the system and can be referenced at a 
later date if you need to — for instance if you ever needed to investigate archived data for a 
possible discrepancy or compare the field value with a printed record. 

View Only 

The last option on the field creation form allows you to designate a field as visible but 
uneditable. There are two general uses for this field: to store data imported from another 
system that you want available for reference to the user, but do not want them to be able to 
modify; or as a data container that is controlled through a custom PHP hook rather than 
through the user interface. CiviCRM has a number of hooks defined that allow developers to 
modify data, as well as customize forms and screens, without modifying the CiviCRM 
codebase. Read the chapter on hooks for more specific information. 

Multiple choice options 

For field types that involve selecting from a set of multiple options - Select, Radio, Checkbox, 
Multi-select and Advanced Multi-select - you are given the option either of using an existing 
set of options which you've already created for another custom field or of creating a new set. 

If you choose to use the same set of options for several fields, then you will be notified when 
making any changes that this will affect an option set that is used by several fields. 

When you create a new set, you have the option of initially entering up to ten multiple choice 
options in a table. If you need more than ten options, you can create an unlimited number of 
additional choices after saving this new field by using the Edit Multiple Choice Options link. 

You may modify the label, order and active status of any multiple option at a later date 
through Custom Data -> View and Edit Custom Fields -> Edit Multiple Choice Options. 
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If desired, you can also mark one of the choices as the default option. The option label' is 
displayed on the form, while the option 'value' is stored in the contact record. The label and 
value may be the same or different. 

Inactive options are hidden when the field is presented. 

CUSTOM DATA SETS 

Custom data fields are organized into sets. These custom data sets can be associated with all 
contact types, with a specific contact type (e.g., Individuals), with a specific component 
(CiviMember, CiviEvent), or with other elements such as Relationships and Groups. 

NOTE: It is important to carefully consider what record type your custom data group will be 
applied to. You will not be able to change the record type after creating your data group. 

When creating field sets you should ask: 

• How will these fields be used? 

• What types of contacts or records will these fields be appropriate for? 

• Will they have broad applicability, or are they relevant to a specific contact type, event, 
contribution type, etc.? 

Taking the time to think through these questions helps keep your application screens as 
relevant and clear of superfluous fields as possible. For example, if your field set contains 
contact characteristics such as a field for the "color of eyes," you would associate them with 
the "Individual" contact type, rather than the generic "Contacts" option, as this field would be 
irrelevant to Organization and Household contact types. Another example would be if custom 
data is specific to particular event registration page than you should create custom data of 
type Participant (Event Type) for the specific Event, rather than just Participant custom data. 

Depending on how many custom data fields you are creating, you should also consider grouping 
the fields topically. For example, you may have 20 custom fields that will all be associated with 
Individual contacts, 12 of which are fields relating to an online membership directory. Rather 
than group all 20 fields in a single custom data set, you may want to split them into two 
groups — one for the directory-related fields, and a second for more general "Individual 
Details." 

You create custom data sets and fields through Administer CiviCRM -> Custom Data -> New 
Group of Custom Fields. Using this form, you identify the title of the data set, specify what 
type of records the data set will be used for, select the display characteristics, and enter help 
text. 
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There are many options in terms of how specifically you can define what the Data Fields will 
be used for. You can use this option to ensure that the fields are only available in the relevant 
places. The full set of options include: 
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• Activity: May be assigned to all activities or to a specific activity type, such as Meeting 
or Phone Call. 

• Addresses: Custom data specific to address block, which allows admin to create 
additional fields related to address. 

• Contacts: Applied to all contact types. If you have created new contact types, you can 
restrict your set to be applied to only to this contact type. 

• Contributions: May be assigned to all contributions or to a specific contribution type, 
such as Donations or Event Fees. 

• Events: Applied to the actual event itself, not the participant registration record, and 
can be assigned to all events or a specific event type (e.g., Conference or Fundraiser) 

• Grants: Fields specific to grant. 

• Groups: Displayed in the Group Settings (note that these fields are not searchable) 

• Household: Applied to household contact type only. 

• Individual: Applied to individual contact type only. 

• Memberships: May be assigned to all membership records or to a specific membership 
type. 

• Organization: Applied to organization contact type only. 

• Participants: Applied to the participant registration record. There are three options for 
participant fields — general fields applied to all registration records, role-type fields 
assigned to a specific participant role, and event participant fields assigned to a specific 
event. 

• Pledges: Fields specific to pledges 

• Relationships: May be assigned to all relationship records or to a specific relationship 
type, such as Spouse of or Employee/Employer of. 

As you can see, custom data sets and fields provide tremendous flexibility and control over 
your data needs, allowing you to create and assign fields to virtually every entity within 
CiviCRM. 

Multiple records 

Data sets usually only have a single set of data associated with a contact record - for 
example, a person has blue eyes or a person has brown eyes. However, there are times when 
you may need to track multiple sets of records for a single contact. CiviCRM provides this 
functionality for custom data sets assigned to contacts (all contact types or a specific type). 
For example, you may want to track a person's post-secondary educational history, collecting 
information about the schools they attended, date of graduation, degree level, and area of 
study. A single person may have multiple records tracking their undergraduate and post- 
graduate work. 

To make use of this option, select the "Does this Custom Data Set allow multiple records?" 
option when creating the custom data set. Note that this option: 

• can only be applied to a data set, not to a particular field 

• the data set must be displayed in a tab (inline display is not supported) 

• can only be used for Contacts, not for Activities, Contributions, etc. 

• cannot be used in Profiles, such as those used for Events 

• cannot currently be exported 

Display style 

Data field sets are either displayed 'inline' on the contact summary page (the Summary tab), 
or as a new Tab sitting along the top of the contact record, along with Summary, Contribution, 
Group, Note etc. Select Tab' for less frequently accessed and/or larger sets of fields. Note 
that this setting applies to Custom Data sets used for Contact records only. Custom data sets 
used for components, relationships, or other resources, are always displayed inline. Also note 
that custom data sets configured to handle multiple records will be displayed in Summary tab. 
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Other settings 

You can specify that you want the field set to be "collapsed" on initial display. If you check this 
box, then only the title for this field set is displayed when the page is initially loaded, because 
the fields are hidden. This is helpful for field sets that are less frequently used as it reduces 
how much screen real estate is used when the page opens. Similar "collapsed" property is 
available on custom data display in Advanced Search. 

You can also set whether the field set is active and can provide explanatory text displayed 
above or below the field set. 

After completing the field configuration options, click save to record the field and return to the 
field listing for your current field set, or click "save and new" to save the field and begin 
defining a new field. 

With the exception of the data and input field type selection, all of the configuration options 
may be modified after your initial creation of the field. You may also find it useful to preview 
your custom fields, as well as the set of custom fields as you are defining them. This is 
particularly useful for checking the layout of radio button and checkbox fields with a large 
number of choices. 

CHOOSING BETWEEN CUSTOM FIELDS, GROUPS AND 
TAGS 

Data fields, groups, and tags are three main ways to associate information with contacts. 
While it can be tempting to just create a custom data field for every attribute of your data, 
take time to learn about the alternatives. They offer powerful functionality that you may miss 
out on if you rely only on custom data. Furthermore, using data fields for information stored 
more appropriately as groups or tags can slow your system. Finally, proper use of groups and 
tags makes it much easier for administrative staff to maintain the records. 

Some tips that may help you choose : 

• Data that can take a wide range of values, such as a person's address or biography, 
should be stored in an alphanumeric custom data field 

• Custom Data fields can be grouped and displayed on their own tab on the contact's 
record 

• As the name implies, Groups are used to group contacts. For instance, you'll probably 
assign board members to one group, staff to another, volunteers to a third, and so on. 
If you use Drupal, you can assign permissions based on group membership. You can also 
define a group that CiviCRM automatically adds contacts to and deletes contacts from, 
based on some characteristic. This feature is called a Smart Group. 

• If you plan to use CiviMail for mass mailings and you want certain contacts to get a 
particular mailing, those contacts must be assigned to a Group. For instance, you may 
want a press release to go only to certain contacts; those contacts should be assigned 
to a particular group. This group could be a Smart Group, 

• Both Tags and Groups can be structured hierarchically. For instance, a group/tag labeled 
Regions can have a subgroup/subtag for each geographic region your organization covers. 
(See "Case study in hierarchical tags" later in this section.) 

• Tags support more powerful search options than data fields or groups. For instance, 
visitors can search through multiple tags with both AND and OR operators. Data fields 
support only lists of words (which is effectively the same as an AND operator), except 
for fields represented as checkboxes, which support OR operators. 

• Tags have a more sophisticated user interface than data fields or groups The interface 
allows the visitor to add and remove tags without reloading the page in edit mode. 

• Custom Data fields can be assigned to a specific record type (e.g., only households), 
whereas tags will be assigned to all types once the tags are defined. 
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USING CIVICRM PROFILE 



A profile is a collection of fields (both predefined and custom) from your database. By creating 
a profile you are able to take only those fields relevant for a specific purpose, such as 
collecting information about a person registering for an event or displaying a directory of 
members on your website. The diagram below provides a visual explanation of how existing 
fields are assigned for use in a profile. 




SCENARIOS 

Profiles provide powerful tools for collecting information from your constituents as well as 
sharing that information through your website. These features can save significant staff time 
by allowing people to update their own data, and you can display up-to-date information from 
your database in a variety of ways. 

For example, a membership-based organisation can provide a searchable membership 
directory on their website that is updated as soon as a new member joins. Another example is 
a form where people can sign up to receive emails from your organisation. Once submitted, 
they are automatically added to the correct email list. Profiles can also be embedded in online 
contribution or event pages to collect additional information about the constituent. 

This section will outline how to use profiles for both collecting and sharing data. 

OVERVIEW 

Profiles provide an flexible set of options for creating forms, directories, and much more. Think 
of a profile as providing a window into your data. Just as you can have many windows in a 
house giving different views of the various objects inside, you can have multiple profiles which 
refer to the same or different fields. 

There are many ways that profiles can be used: 
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• Forms: a profile can be used as a form to collect information from your contacts. You 
can also add profiles to contribution, membership sign-up, and event registration pages 
to collect additional information from donors, members, and event participants. Profile 
forms can also be used as simplified data entry forms. 

• View/edit user account (Drupal only): it is often useful to allow your constituents to 
manage their own data through your website. This use of profiles allows people to edit 
their information when they are managing their Drupal account; this information is then 
automatically updated in CiviCRM. 

• Website user registration: you can include a set of fields in the new account 
registration form (Drupal) or create a profile that includes website user registration fields 
Ooomlal). 

• Directory: a profile can be used to create a searchable directory for visitors to your 
site. 

• Search results: using profiles allows you to display selected fields in the results of an 
advanced search. 

• Batch data updates (mass updates): there is often a need to update a large number 
of records all at once; this process can be streamlined using profiles. 

Another important point about profiles is that the same profile can be reused in multiple ways. 

COLLECTING DATA FROM CONSTITUENTS 

This section reviews the different methods by which you can use profiles to collect information 
from your constituents. A later section will discuss how to share information from CiviCRM 
with your constituents. 

Volunteer sign-up form 

Let's walk through an example of a profile used as a volunteer sign-up form. This simple form 
includes fields for First Name, Last Name, and Mailing Address. It also includes a reCAPTCHA 
widget to protect your site from automated abuse (described further below). 

Signup 



First Name • 














Last Name ■ 


1 










Street Addre* i 






1 














at* 










Portal Code 








Country f 


Jnitfd States HQJ 






State / Province 


select ■ 




:' 
















them 




vtfa 






rypalhe twg won}*: 




a 















To build a a form similar to this one: 
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1. Go to: Administer > Customize > CiviCRM Profile and click on Add CiviCRM Profile. 

2. Give the profile a meaningful name, and mark it to be used for a Profile: 



Profile Name 
Used For <¥> 


r 














Drupal User 


Reg 


strati on 


GVi 


ew/Edit Drupal User 


.Account 














■ 


Profile 


[J 


Search Resi 


ita 


i — i 



3. The next two text fields allow you to include help text to assist the person filling out the 
form. 

4. The remaining options are listed under Advanced Settings (click on the gray bar to 
expand this section): 
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1. Limit listing to a group: this is very important. If the profile is used for a 
searchable directory, by default CiviCRM will expose every record in your 
database; this is not ideal in many cases. Use this setting to limit the available 
records to contacts who are part of a regular or smart group. For example, if an 
organisation needs to limit a profile listing to show only active members, they can 
create a smart group of all members that have a status of New and Current. 
They then limit the directory to only show contacts in that smart group. 
Remember, smart groups are dynamic lists of records; when new memberships 
are added, the corresponding contact will automatically be included in the 
directory. 

2. Add new contacts to a group: this is applicable when using a profile as a sign-up 
form. You are able to directly add all the contacts who fill out the profile form to 
a particular group. For example, if your profile form asks contacts to offer their 
services as a volunteer, then all those who fill out the form can be automatically 
be added to a volunteer group. 

3. Notify when profile form is submitted?: who in your organisation should receive 
an email when someone fills out the form? Enter their email address here. If you 
want to send email to multiple addresses, separate them with a comma. 

4. Redirect URL: when someone clicks Save to submit the form, do you want to 
take them to a specific URL? Normally you would create a special thank-you page 
on your website to redirect people to. If this field is left blank, the user will be 
directed to a page which displays the information they've just entered (a profile 
view page). This setting does not apply if you embed your form in an event sign-up 
or contribution form. 

5. Cancel Redirect URL: similar to the previous item, what is the URL you want to 
redirect people to if they click Cancel on the form? Again, this setting does not 
apply if you embed your form in an event sign-up or contribution form. 

6. Include reCAPTCHA: CAPTCHA is a type of spam blocking software that requires 
the visitor to fill in text generated from a graphic. This prevents automated 
spiders (robots) from completing the form. It is highly recommended that you 
include it. You must have configured a free reCAPTCHA account before enabling 
this. Go to Administer > Configure > Global Settings > Miscellaneous Settings to 
configure your account (click the help icon for on that form for detailed 
instructions). 

7. What to do on duplicate match: use this option to control what happens when 
the contact data submitted from this profile matches an existing contact record. 
Options are to update the matching record, create a duplicate record, or give the 
user a "duplicate record" warning (in which case their input will not be saved). This 
setting is ignored if the profile is embedded in an online contribution, membership 
sign-up or event registration form. In these cases, a contact match always results 
in the transaction being linked to the matching contact. Note that if there are 
multiple matching contacts, the first matching record is used. 

8. Proximity search: if you are using this profile as a search form, you can choose 
to include proximity searching. When enabled, a proximity search block will be 
added to the search criteria. This block contains fields to set the proximity start 
address, and a field to set a "radius" (distance from that address). Set the 
proximity search as required if you want all searches using this profile to force the 
user to enter a start address and a radius. 

Once you have saved the profile settings, it's time to add fields to the profile. If you plan to 
reference custom fields in a profile form, make sure that those fields have already been 
created. 

Some important notes on adding fields: 
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You can change the name of a field label for the profile. For example, the Postal Code 
field can be renamed Zip Code if your audience is more familiar with that term. 
Certain fields can be required (must be filled out). In this scenario, we would want to 
make at least First Name and Last Name required, and probably some sort of contact 
information such as email address and/or phone number. 

You can make a field View Only, which means it will be displayed on the profile form but 
not editable (this setting is not relevant for the volunteer sign-up scenario). 
If the profile is being used as a searchable directory, set the Visibility of any fields you 
want to include on the search form to Public Pages or Public Pages and Listings. For our 
volunteer sign-up scenario, we are only using the profile as a sign-up form, so we can 
set Visibility to User and User Admin only. This ensures that other visitors can not view 
any form data. 



CiviCRM Profile Field 

Field Name 




fcOTS fcanuisM lai 


I Individual £ 1 1 First Nanne 


Field Label 


Select the type of CiviCRM record and the field you want to indi 


| First Name 


The field label displayed on the form (over-ride the default field 


Required? 







Are users required to complete this field? 


View Only? 


D 




If checked, users can view but not edit this field. 


Visibility * 


NOTE: View Only fields can not be included in Profile Search for 


I Public Pages and Listings S | 




Is this field hidden from other users ('User and User Admin Onh 




('Public Pages' or 'Public Pages and Listings')? When visibility is ' 




contact in order to locate other contacts with the same value(s) ( 


Searchable? 


a 




Do you want to include this field in the Profile's Search form? 



Linking to your Form 

Once your profile sign-up form is built, it is ready to be used! There are several ways to do 
this. 

• Drupal: if you intend to give your volunteers access to some back-office CiviCRM 
functions, you can add an item to the CiviCRM navigation menu which links to this form 
(from Administer > Customize > Navigation Menu). These users will need be given the 
"access CiviCRM" permission. 
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• Drupal: create link(s) to the form using the following path: 
http://www.myorganization.org/civicrm/profile/create?reset=1&gid=N where N is 
the ID of the profile (each profile has a unique numeric ID which you can find by going to 
Administer > CiviCRM Profile and checking the third column of the table). 

• Drupal: create a link or a menu item for logged-in users to edit their own information. If 
they are logged in and go to the profile URL, the fields of the profile will be prepopulated 
and they will be able edit any fields needing updating. The URL path here is: 
http://www.myorganization.org/civicrm/profile/edit?reset=1&gid=N where N is the 
ID of the profile. 

• Joomla!: use the Menu Manager to create a front-end menu item. After creating a new 
menu item, select CiviCRM and choose the type of profile display you would like to use. 
In the parameters pane, choose the specific profile to use. 

• A great feature is to provide non-logged-in users with is the ability to view and edit their 
contact information via a profile using CiviMail. To do this, insert the following link with 
appropriate tokens as shown into a CiviMail message: 
http://www.myorganization.org/civicrm/profile/edit? 

reset=1&gid=N&id={contact.contact_id}&{contact. checksum} where N is the ID of 
the profile form you want them to use for editing. The token {contact. checksum} 
generates a special link that prepopulates the fields of the profile with any information 
that already exists for them in that profile. The special link lasts for 7 days from the day 
you send the mailing. This feature can be used for either Drupal or Joomla! sites. 

• The last option is to not link directly to the profile at all, but simply embed the profile 
form into any page on your website - or ANY website, for that matter. On the Profiles 
Administration page there is an option called Standalone Form. Clicking it takes you to a 
screen where you can copy the raw HTML code and paste it into any page on your site 
or any website where you want to collect information. Make sure the reCAPTCHA 
feature is NOT enabled for this profile; reCAPTCHA requires dynamic page generation so 
submitting a standalone form with reCAPTCHA enabled will always result in an error. 

DATA ENTRY TOOL 

If you have volunteers or interns who perform manual data entry for your organisation, you 
can make their task easier by creating a profile form which shows only the fields they need to 
input. This greatly simplifies data entry and reduces the chance of data being incorrectly 
entered. 

INCLUDING PROFILES ON EVENT REGISTRATION AND 
CONTRIBUTION PAGES 

Often you will want to define certain fields for inclusion in event registration and contribution 
pages. This process is similar to the volunteer sign-up example above. The only significant 
difference is that you can include fields in your profile that are specific to participant records 
(for event registration forms) and contributions (for contribution pages). Read the sections 
covering creating contribution pages and event registration pages for more information. 

INCLUDING PROFILES IN DRUPAL'S USER REGISTRATION 
SCREEN 

For websites that have logged-in users, you may want to allow people to provide additional 
information as they register for an account on your website. Similarly, when people fill out a 
profile form you may want to encourage (or force) them to sign up for a user account. 

To include a profile form during the user registration process: 
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1. Create a profile that is used for User Registration: 



Profile Name * Contact Information 



Used For Q D Profile EH Search Results iyj User Registration d View/Edit User Account 

2. Add the fields you want people to fill out as they register, using the same process 
described above. Make sure the field visibility is set to Public User Pages. 

INCLUDING PROFILES IN DRUPAL'S MY ACCOUNT SCREEN 

You can embed one or more CiviCRM profiles directly into Drupal's My Account screen. This 
makes it easy for logged-in users to review and update their information whenever they visit 
their My Account page. 

To create a profile for this purpose: 

1. Create a new profile, or navigate to an existing profile and click Settings. 

2. Select View/Edit User Account in Used For. 

3. Click Save. 

4. Add the fields you want people to be able to edit from their Drupal My Account page. 

NEW ACCOUNT CREATION DURING PROFILE SIGN-UP 

If you want your constituents to create a Drupal or Joomla! account when filling out a profile, 
you can enable this with the "User account registration option" under Profile Settings > 
Advanced Settings. Anonymous (not-logged-in) users will then be invited (or required) to create 
an account when they visit the profile. Logged-in users will just see the profile fields. 

Drupal user _. no account create option — Give option, but not required 
account o . _, __ 

v Account creation required U 

registration ^ ■■ 

option? 

You must include a Primary Email Address field in the profile for this feature to function 
properly. This feature also works when the profile is embedded in an online contribution page 
or event registration page. Hence you can invite or force anonymous visitors to sign-up for an 
account when they register for an event. 

SHARING INFORMATION 

Profiles and directories 

Many organisations have data they would like to display on their website. Historically this has 
been difficult because it required updating the same data in two places - a website and a 
database. Using CiviCRM profiles solves this problem because it allows you to expose data 
from your database on your website while only needing to manage and update the data in 
CiviCRM. 

For example, an organisation called Native Americans in Philanthropy (NAP) wanted to create a 
membership directory that their members could use to search and connect with other fellow 
members. Before CiviCRM, they would create a very expensive annual print directory and mail 
it to every member. This process was time-consuming and expensive, and some data would 
be out-of-date before the members received their directory. Switching to CiviCRM meant 
significant resource savings and, because their website became a portal for their members to 
connect, it helped to advance their mission. 

To build your directory: 
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1. Go to: Administer > Customize > CiviCRM Profile. 

2. Click Add CiviCRM Profile. 

3. Set Used For to Profile: 

Profile Name * j Membership Director^ | 

Used For Q ^Profile Q Search Results 

4. Advanced Settings: there are a few options under advanced settings that are helpful 
when using profiles for directories. 

1. Enable mapping: a really cool feature available in CiviCRM is to allow visitors to 
map contacts in your directory using Google or Yahoo! maps. They can then obtain 
directions to a record's address dynamically. To use this feature, you must have 
already enabled mapping under Administer > Configure > Global Settings > Mapping 
and Geocoding. 

2. Include profile edit links: check this box if you want to include a link in the 
directory listings to allow people to edit the profile's fields. Only users with 
permission to edit the contact will see this link. More often than not you will not 
need to enable this setting as it is not commonly used in the membership 
directory scenario. 

3. Include Drupal user information (Drupal only): check this box if you want to 
include a link in the directory listings to view a contacts' Drupal user account 
information (e.g. their My Account page). This link will only be included for contacts 
who have a user account on your website. 

□ Enable mapping for this profile? Q 

G Include profile edit links in search results? Q 

D Include Drupal user account information links in search results? Q 



Now it's time to include the fields that will make up the directory. For profiles used as 
directories you have total control over which fields: 

• are searchable in the directory 

• appear in the results columns of your search 

• appear in the record detail View page. 

The important options you must configure in the fields for directory purposes are shown 
below: 



Visibility * | Public User Pages and Listings v| 

Is this field hidden from other users ('User and User Admin C 
Search form ('Public User Pages' or 'Public User Pages and Li< 
also click the field value when viewing a contact in order to lo 
live in Poland). 

Searchable? □ 

Do you want to include this field in the Profile's Search form? 
Results Column? rj 

Is this field included as a column in the search results table? 
User Pages and Listings' visibility. 
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• Visibility for all fields in your directory must be set to Public Pages or Public Pages 
and Listings. The difference between these two options is that those configured as 
Public Pages and Listings will have the field in detail view hot-linked, enabling the user to 
generate a follow-up search for other records which also have that same field value. For 
example, you might set City to Public Pages and Listings. After the user conducts a 
search and views the details for a record they can click on the city value and run an 
immediate search. The search will run as if they had selected that city in the profile 
search screen. 

• The Searchable option determines if visitors to your directory can search the directory 
by this field. In common directory uses, almost every field is set to searchable. The 
more fields you set to searchable, the more power you provide to your visitors to find 
the information they need. 

• The Results Column check-box determines if the the field is displayed as a column in 
the list of results. For example, your directory may have a field for website, and if you 
set the website field to appear in the results column, it will appear in the results table. If 
you do not check the results column the field will still appear in the view mode for a 
record. In other words, checking Results Column? will allow the field to appear in the 
results column AND in detail view mode. 

The image below shows the search mode for our membership directory. 

Membership Directory 



B Sea 

Name 

City 

Email 


ndi 



Criteria 


1 








>earch J 



Once you hit search you get this result set. Profile fields that have Results Column checked 
are shown in the listing. 





— Name 


City 


- Email 


: Website 




ft 


Alliance for Good 


New York 


help@alliancegood.org 


http://alliancegood.org 


View | Edit 


a 


Floss Manuals 


Berlin 


info@flossmanuals.net 


http://en.flossmanuals.net 


View | Edit 


a 


Save Our Planet 


Seattle 


info@estample.org 


http://www.example.org 


View | Edit 



Clicking the view link gives you more details about the constituent, showing all profile fields. 

Membership Directory - Floss Manuals 

Member Name Floss Manuals 

City 3erhn 

Email info@fiossmanuals.net 

Website http://en.flossmanuals.net 

As we've seen, building a directory for your website can provide a valuable tool for your 
constituents. 

Linking to Your Directory 

You have several options to link to your directory: 
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• Drupal: link to the directory search page using this path: 
http://www.myorganization.org/ 'civicrm/profile?reset=1&gid=N where N is the ID of the 
profile directory. 

o If you add &force=1 to the above URL it will directly show a result set. 
o If you add &force=1&search=0 it will hide the search criteria and directly show 
the result set. 

• Joomla!: use the Menu Manager to create a front-end menu item. After creating a new 
menu item, select CiviCRM and choose the profile search option. In the parameters pane, 
choose the specific profile to use. 

• You can also prepopulate any search criteria in the URL. These options are described 
here: 
http://wiki.civicrm.org/confluence/display/CRMDOC/Linking-l-Profiles 

OTHER PROFILE USES 

Search results 

Searching is outside the scope of this section but, assuming you are familiar with searches, 
you may wish to change the columns used to display the results of an advanced search. To do 
this: 

1. Create or open a profile and mark it as used for Search Results: 



Profile Name • I Custom Search Results 



Used For Q D Profile Search Results □ User Registration D View/Edit User Account 

2. When adding fields to this profile, you will need to set Visibility for the fields to Public 
Pages and check the Results Column? box. 

When conducting your advanced search, use the Search Views dropdown menu in the top right 
of the page to select your profile. 

Batch updates 

The final way that profiles can be used is to perform batch updates of data. For example, you 
have a custom field called "volunteer interests" and you want to update the volunteers group 
with a certain interest. You can easily update the entire group using a profile. 

1. Create or open a profile and mark it as used for Profile: 



Profile Name " Update vol Lint ear interests 



Used For Q Profile □ Search Results LI User Registration □view/Edit User Account 

No other profile settings are relevant for this type of usage. 

2. Add your fields to the profile. Only add the fields you want to batch update. In the 
above example, the only field you would need is your custom "volunteer interests" field 
(contact name is always displayed when doing batch update). Remember, fields added to 
the profile must all be of the same contact type. You cannot add fields that are specific 
to both organisations AND individuals. 

Once your profile is created, and you have conducted your search, select Batch Update via 
Profile from the actions dropdown menu and click Go. Then select the profile you want to 
use. 
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149 Results 

Select Records: All 149 records O Selected records only 


Print 


- more actions - j0 


L^oj 




- more actions - 








Add Contacts to Group 
Add Contacts to Household 
Add Contacts to Organization 


^0000000 


Delete Contacts 
Export Contacts 
Mailing Labels 




□ * 


-City 


□ a 


Map Contacts 
New Smart Group 
Record Activity for Contacts 
Remove Contacts from Group 
Schedule/Send a Mass Mailing 
Send Email to Contacts 
Tag Contacts (assign tags) 
Untaq Contacts (remove tags) 




□ ft AB 




n a Ad 




□ ft Ad 


and Rd SW Mount Vernon 









You will see a grid with the fields in your profile. You can update each field and row individually. 
If there is a field where you want to enter the same value for ALL records, you can enter that 
value in the first row and then click on the "copy values" icon to the left of the column 
header. This will copy the field value to all the rows in your grid. 



Name 



testate (Home) 



Smith, Chetan 



G 



Patel, Jennifer [ Texas 
Zope, Michelle I Texw 



[£) Volunteer Interests 



_5§ C Education © Envl 



rsnment — Social Justice 



Education _ Environment - Social Justice 
Education - Environment - Social Justice 



Don't forget to click the Update Contacts button at the bottom of the page to save your 
changes. 

Batch update limitations 

• You cannot perform batch updates for different types of contacts (individuals and 
organisations, for example) at the same time. 

• If you wish to update participant fields, you must do the update from a Find Participants 
search (and only include participant fields in your profile). 

• You may only perform a batch update for 100 records at a time. 

COMBINING RECORD TYPES IN A PROFILE 

A profile usually contains fields of one record type. For example: First Name and Last Name 
(Individual fields). But in some cases, such as online event registration and online contribution 
pages, you can combine fields from two different record types (e.g. Individual + Participant 
fields or Individual + Contribution fields). You can also combine Individual fields with general 
Contact fields (e.g. Last Name + Email Address). 

If you try to combine fields with an unsupported combination of record types, you'll get an 
error when you try to save the field. 
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10. 



INSTALLATION 



Before reading further, please be aware that much of the information contained here is 
intended for technicians and may be difficult to understand if you have little or no experience 
in setting up web applications. If you don't understand this topic, you may wish to either seek 
help, or point your organisation's technical staff to this material. 

INSTALLATION 

CiviCRM must be installed on a computer that has been configured with a web-server, PHP, 
and MySQL. Some people prefer to try out CiviCRM on their own local computer before 
installing it on a dedicated web-server. If you are doing this and don't have the pre-requisites 
mentioned above, you can download packages such as WAMP, XAMPP, MAMPP and LAMP off 
the internet which will quickly install Apache web-server, PHP and MySQL. (The first two 
packages are for Windows and the second two are for Macintosh and Linux respectively). 

Once you are ready to start using CiviCRM in your organization you'll probably want CiviCRM to 
be available on the internet. However, some organizations only want internal staff to have 
access. In this case they may choose to install CiviCRM on an intranet or internal network. 

Before you can begin the installation process, you will need to decide whether you are going to 
use CiviCRM integrated with Drupal or Joomla. Refer to the appropriate section in the online 
CiviCRM Installation Guide for the latest system requirements and specific installation steps: 

http://wiki.civicrm.org/confluence/display/CRMDOC/lnsta Ha tion+and+Upgrades 
A Note About Upgrades 

New versions of CiviCRM are released two or three times a year - and you will need to apply 
upgrades to your CiviCRM site periodically in order to take advantage of new features and 
improvements. It's important that you plan for the resources (people and time) required to 
apply upgrades to your site. You need to plan on testing upgrades on a copy of your live site 
to make sure the process runs smoothly. It's critical to make backups of your site and 
database prior to running an upgrade. 

Refer to the appropriate section of the online CiviCRM Installation Guide for specific upgrade 
procedures. Be sure to select the procedure that is targeted for the environment you are 
running (Drupal or Joomla), and the version you are upgrading to. 

CONFIGURATION 

Now that you have CiviCRM installed and running on your web-server, it's time to review the 
initial configuration tasks which allow you to customize CiviCRM for your organization. 

You can easily access each of the configuration screens described below from the 
Configuration Checklist. Login to your CiviCRM site and navigate to Administer CiviCRM -> 
Configure -> Configuration Checklist. This section will cover the general tasks, while 
component-specific configuration will be covered in each component section. 
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Site Configuration 



Localization 



Domain Information 



Localization settings include user language, default currency and 
available countries for address input, 

Organization name, email address for system -generated emails, 
organization address 



iewing and Editing Contacts 



Site Preferences 

Address Settings 
Mapping and Geocoding 
Miscellaneous 



Configure screen and form elements for Viewing Contacts, 
Editing Contacts, Advanced Search, Contact Dashboard and 
WYSIWYG Editor. 

Format addresses in mailing labels, input forms and screen 
display. 

Configure a mapping provider (e.g. Google or Yahoo] to display 
maps for contact addresses and event locations. 

Contact search behaviors, ftECAFTCHA configuration. 



Sending Emails (includes contribution receipts and event confirmations} 



Outbound Email 



From Email Addresses 



Settings for outbound email - either SMTP server, port and 
authentication or Sendmail path and argument. 

Define general email address(es) that can be used as the FROM 
address when sending email to contacts from within CiviCRM 
(e.g. info@example.org) 

Online Contributions / Online Membership Signup / Online Event Registration 



Payment Processors 

Permissions for 
Anonymous Users 



Select and configure one or more payment processing services 

for online contributions, events and / or membership fees. 

You will also need to change Drupal permissions so anonymous 
users can make contributions, register for events and f or use 
profiles to enter contact information, (learn more..,) 



A Note about "Tokens" 

It's helpful to understand the term token before you continue reading this section. Tokens are 
special blocks of text which refer to a specific field in your database. They are used to control 
what fields are included in address display and mailing labels, and can also be used to 
personalize emails. This is described in more detail below. If you've used "mail merge" in your 
word processor, then you've already used tokens. 

CiviCRM uses tokens to control which fields are included in mailing labels and address display, 
and how they are arranged. Tokens are always surrounded by curly brackets, and include the 
record type followed by the field name. EXAMPLE: {contact. street_address}. Address values are 
taken from the contact's primary location. 

Tokens are skipped when they refer to a field that is empty for a particular contact. 

EXAMPLE: The default Individual Name Format includes {contact. middle_na me}. If a contact 
doesn't have a middle name, that token is skipped. 

EXAMPLE: The default Mailing Label format includes {contact. supplemental_address_l} on a 
separate line. If there is no supplemental address for a particular contact, that entire line is 
omitted - there will NOT be a blank line in the label. 

LOCALIZATION 

Localization involves adapting CiviCRM for use in a specific country or language by translating 
the text displayed on the screen and setting region specific formats for dates and money 
(including currency). By default CiviCRM is "localized" for the United States. If you are using 
CiviCRM in a different country or countries, or you need to store contact addresses in 
countries other than the United States, or you want to use CiviCRM in another language, you 
will need to review and update the values on this screen. 
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CiviCRM has been translated into a number of different languages. These translations are 
contributed by community members - so your first step is to determine if a complete 
translation exists for the current version by visiting the Translation Server home page at 
http://translat ions, civicrm.org/ . If you find a completed translation, you can download it and 
select it on this screen. Otherwise you will need to consider whether you have resources for 
contributing a translation. 

It is also possible to configure your site to support multiple languages. In this mode, your users 
will be able to choose from a list of available languages after logging in. You can also create 
and store multi-language versions of text that is added by your users. Examples include 
custom field labels, online contribution page, campaign information, and event descriptions. 

Further reading: 

Localization overview - http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM-l-Localisation 

DOMAIN INFORMATION 

Use this screen to enter identifying information for the organization or entity which "owns" 
this CiviCRM installation. The organization name and address are used to identify your 
organization in CiviMail mailings when you include the domain.name and domain.address 
tokens. 

You should also enter a valid email address that belongs to your organization which will be 
used as the FROM email in system-generated (automated) emails. 

SITE PREFERENCES 

This screen allows you to modify the screen and form elements for the following tasks: 

• Viewing Contacts - Control the tabs that should be displayed when viewing a contact 
record. EXAMPLE: If your organization does not keep track of 'Relationships', then un- 
check this option to simplify the screen display. Tabs for Contributions, Pledges, 
Memberships, Events, Grants and Cases are also hidden if the corresponding component 
is not enabled 

• Editing Contacts - Control the sections that should be included when adding or editing a 
contact record. EXAMPLE: If your organization does not record Gender and Birth Date 
for individuals, then simplify the form by un-checking Demographics. 

• Contact Search - Control the sections that should be included in the Advanced Search 
form. EXAMPLE: If you don't track Relationships - then you do not need this section 
included. Simplify the form by un-checking this option. 

• Contact Dashboard - This dashboard can allow your constituents to view the groups 
they are subscribed to, their contribution history, event registration information and 
more. You can control the sections that should be included in the dashboard here. 
EXAMPLE: If you don't want constituents to view their own contribution history, un- 
check that option. 

• WYSIWYG Editor - Select the HTML WYSIWYG Editor that is provided for fields that 
allow HTML formatting (such as the introductory section for your online contribution 
pages). You can choose either CKEditor or TinyMCE. It's a good idea to try out both and 
see which is more comfortable for you and your users. 

• Individual Display Name - Display name format for individual contact display names. 

• Individual Sort Name - Sort Name format for individual contact sort names. 

ADDRESS SETTINGS 
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CiviCRM allows you to modify the default fields for adding and editing contact and event 
address data. You can also change the address field layout used for screen display and mailing 
labels. Review the out-of-the-box defaults by adding a new contact record and noting the 
address fields provided on the form. Save the record and note the order in which the fields 
are displayed on the Contact Summary screen. If you plan on generating mailing labels for 
contacts - you should also review the label layout (select Mailing Labels from the -actions- 
drop-down after doing a search using the Find Contacts menu option). 

After reviewing the default fields and layouts - review the Address Settings screen and make 
changes as needed. 

• Mailing Labels - Modify mailing label formatting here. The default format is: 

{contact . addressee } 

{contact . street _address } 

{contact . supplemental_address_l } 

{contact . supplemental_address_2 } 

{contact . city} { , } {contact . state_province} { } {contact .postal_code } {contact . 

You must include the special {contact.addressee} token here in order to include the 
addressee in your labels. Users will be able to select from a variety of label types 
corresponding to the label manufacturer code when they generate the labels from a list 
of contacts. It's a good idea to test your format with the type of label and printer you 
plan on using to verify spacing. 

• Address Display - Modify the layout for contact and event location addresses when 
displayed on CiviCRM screens. The default format is: 

{contact . address_name } 

{contact . street _address} 

{contact . supplemental_address_l } 

{contact . supplemental_address_2 } 

{contact . city} { , } {contact . state_province } { } {contact .postai_code } {contact . 

TIP: This format applies to event locations, despite the use of the contact, record type 
in the layout. The {contact.addressname} token is particularly useful for events where 
you need to include a location name (e.g. "Smithson Hall"). 

• Address Editing Fields - Modify the available address editing fields here. You can hide 
fields that you don't plan on using in order to simplify the forms. EXAMPLE: If you don't 
plan on recording OpenlDs for contacts, you can uncheck that field. 

o Street Address Parsing - CiviCRM uses the US Postal Service's (USPS) Postal 
Addressing Standards to parse an address into fields to hold the address 
elements: Street Number, Street Name, and Apt/Unit/Suite. It's best practice 
to enter address information that conforms to the Postal Addressing Standards, 
not only for consistency in your data, but also to best take advantage of the the 
Street Address Parsing function. You can edit and or view the parsed address by 
clicking on Edit Address Elements next to the Street Address field of the 
Address Area of the Summary tab when viewing a contact record. You can learn 
more about USPS' Postal Addressing Standards at 
http://pe.usps.com/text/pub28/welcome.htm . 

• Address Standardization - CiviCRM includes an optional feature for interfacing to the 
United States Postal Services (USPS) Address Standardization web service. You must 
register to use the USPS service at http://www.usps.com/webtools/address.htm . If you 
are approved, they will provide you with a User ID and the URL for the service. The URL 
provided by USPS will not be prefixed with "http://". When entering this URL into the 
CiviCRM settings field, you must prefix it with "http://". 

MAPPING AND GEOCODING 

CiviCRM includes support for both the Google and Yahoo mapping services. These services 
allow your users to display contact addresses and event locations on a map. To enable this 
feature, select your mapping provider and obtain a 'key' for your site from that provider. 
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Once a mapping provider is enabled, your contact and event records will be automatically 
geocoded (the latitude and longitude for that address is inserted) as you add or edit address 
data. 

SEARCH SETTINGS 

Adjust search behaviors including wildcards, and data to include in quick search results. 
Adjusting search settings can improve performance for larger datasets. 

A wildcard character is a special character that can be used to substitute for any other 
character or characters in searches. CiviCRM allows you to use the percent - '%' - character 
to substitute for zero or more characters, and the underscore - '_' - character to substitute 
for any single character. Wildcards are useful for broadening your search results. 

EXAMPLE: Typing 'Volunteer // as your Activity Subject will match any record whose subject 
contains 'Volunteer' + any other words (e.g. 'Volunteer for Open House'). 

• Automatic Wildcards - By default, wildcards are automatically added when users 
search for contacts by Name. EXAMPLE: Searching for 'ada' will return any contact 
whose name includes those letters - e.g. Adams, Janet', 'Nadal, Jorge', etc. Disabling this 
feature will speed up searches significantly for larger databases, but users must use 
wildcard characters for partial name searches (e.g. '%' or '_'). 

• Include Email - By default, email addresses are automatically included when users 
search by Name. Disabling this feature will speed up searches significantly for larger 
databases, but users will need to use the Email search fields (from Advanced Search, 
Search Builder, or Profiles) to find contacts by email address. 

• Include Nickname - By default, nicknames are automatically NOT included when users 
search by Name. Change this value to Yes if you want nicknames to be included. 

• Include Alphabetical Page - If disabled, the alphabetical pager will not be displayed on 
the search screens. This will improve response time on search results on large datasets. 

• Include Order By Clause- If disabled, the search results will not be ordered. This will 
improve response time on search results on large datasets significantly. 

• Smart group cache timeout - Smart groups are basically saved searches. The list of 
contacts for each smart group is cached in the database in order to avoid running the 
saved search every time you access a smart group. This field determines the number of 
minutes to maintain this cache before refreshing it. The default value of means the 
cache is emptied immediately when any contact is edited or a new one is added. If your 
contact data changes frequently, you may want to try setting this to a value of 5 
minutes (or longer) to reduce processing load on your server. 

• Autocomplete Contact Search - Selected fields will be displayed in autocomplete 
dropdown lists and the "Quick Search" box on the navigation menu. The contact name is 
always included. 

MISCELLANEOUS: VERSION CHECKING, RECAPTCHA 

Use the Miscellaneous Settings screen to configure and control the following behaviors: 
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• Dashboard Cache Timeout - The number of minutes to cache dashlet content on 
dashboard. 

• Contact Trash and Undelete - If enabled, deleted contacts will be moved to trash 
(instead of being destroyed). Users with the proper permission are able to search for the 
deleted contacts and restore them (or delete permanently). 

• Version Checking and Statistics Reporting - This feature automatically checks 
availability of a newer stable version of CiviCRM. New version alerts are displayed on 
the main CiviCRM Administration page. Statistics about your CiviCRM installation are also 
reported anonymously to the CiviCRM team to assist in prioritizing ongoing 
development efforts. The following information is gathered: CiviCRM version, versions of 
PHP, MySQL and framework (Drupal/Joomla/standalone), and default language. Record 
counts (but no actual data) are also reported. You can set this field to No if you are not 
comfortable with having this information reported for your site. 

• Attachments - You can increase or decrease the maximum number of files (documents, 
images, etc.) which can attached to emails, activities, and grant records. The default 
value is 3. 

• File Size - Maximum Size of file (documents, images, etc.) which can attached to emails 
or activities. Note that php.ini should support this file size. 

• reCAPTCHA - reCAPTCHA is a free service that helps prevent automated abuse of 
your site by requiring users to read a random pair of words and type them into the 
form. To use reCAPTCHA on public-facing CiviCRM forms: sign up at recaptcha.net : enter 
the provided public and private reCAPTCHA keys here; then enable reCAPTCHA under 
the Advanced Settings section in any Profile. 

If you want to use reCAPTCHA protection for online contribution, membership signup or event 
registration forms - then you'll need to configure a Profile with reCAPTCHA enabled, and then 
include it in those forms. 

CONTACT TYPES 

You can modify the names of the built-in contact types (Individual, Household, Organizations), 
and you can create or modify "contact subtypes" for more specific uses (e.g. Student, Parent, 
Team, etc.). 

SENDING EMAILS 

CiviCRM will use the default FROM address defined here when sending automated emails. If 
you've already entered an email address in the Domain Information screen, that address will 
be listed here. 



Label Value Description Order Default Reserved Enabled? 



"Client Services" 2 Use this for 1 [x] No Yes 

<clientservices@example.org> all general 

emails. 



When users send an email using CiviCRM, their primary email address is used as the FROM 
address by default. However, they can also select one of the general email addresses defined 
here as an alternative. 

Outbound Email 

If you are sending emails to contacts using CiviCRM then you need to enter settings which 
allow CiviCRM to connect to your mail server. This includes sending receipts to contributors, 
sending confirmations to people registering for events, and using CiviMail to send bulk mailings. 
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CiviCRM supports two different methods of connecting to a mail server: SMTP (Simple Mail 
Transport Protocol) OR Sendmail. Each method requires that you enter specific settings. If 
you're unfamiliar with these terms, or unsure of the correct values for these settings, check 
with your system administrator, ISP or hosting provider. 

You should always send a test email when you enter or modify the settings on this screen. 
Simply click "Save and Send Test Email". An email will be sent to the email address associated 
with your user login. The FROM email address will be the default FROM address you've 
configured in the previous section. 

fsayej (cancel") (save & Send Test Email J 

If CiviCRM is unable to send the test email, you will see a message on your screen with the 
specific error and some suggestions for trouble-shooting the problem. 

Note: If you do NOT want users to send outbound emails from CiviCRM at all, select "Disable 
Outbound Email". However, if you disable outbound email, and you are using Online 
Contribution pages or online Event Registration - you will need to turn off the automated 
receipting and registration confirmation features (these are enabled by default). Otherwise 
your constituents will see error messages after they've completed a contribution or 
registration. 

PAYMENT PROCESSORS 

Payment processors are companies that handle credit card transactions for merchants and / 
or non-profit organizations and transfer funds to the organization's bank account. If you plan 
on using CiviCRM to accept online contributions, online membership signup and renewal or 
online event registration, then you will need to select and configure a payment processor for 
your site. 

CiviCRM includes support for several different processors, and provides a way for 3rd party 
developers to add support for additional processors based on their clients' needs. Each 
processor has their own pricing structure and features, and you will want to investigate each 
available option to determine the best fit for your organization. Refer to the "Contributions" 
section for a list of factors to consider in selecting a processor. 

The actual steps involved in configuring and testing your payment processor connection are 
different for each processor. For more information, visit: 
http://wiki.civicrm.org/confluence/display/CRMDOC/CiviContribute+Payment+Processor+Configuration 

PERMISSIONS FOR ANONYMOUS USERS 

Note: This section applies to Drupal sites only. 

If you are using CiviCRM with Drupal, you will need to review user permissions to ensure 
that people can get to your signup forms, contribution pages, membership pages and event 
registration pages. 

You must be an administrator for your Drupal site to review and modify user permissions. 
Login to your Drupal site, and navigate to Administer » User Management » Permissions. 

anonymous 
Permission 

user 

civicrm module 
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make online 

contributions 





profile listings and 
forms 


•■/ 


register for events 






Then review each of the permissions listed below. You should enable them for the 
anonymous user role if you want these features to be accessible to people who are visiting 
your site but are NOT logged in: 

• Make online contributions: 

If you plan to use CiviContribute and want to allow online contributions, enable this 
permission by checking the box. 

• View event info and Register for events: 

If you plan to use CiviEvent and want to allow online event registration, enable BOTH of 
these permissions. 

• Profile listings and forms: 

If you want to either collect contact information from constituents and/or expose a 
searchable directory using a profile, you must enable this permission. 

• Access all custom data: 

You must enable this permission for any role which you want to view or edit custom 
data fields. This permission sounds like one that should be given out with care but in 
reality most sites give this permission to anonymous users as it is required for simple 
tasks like filling in information about themselves in custom data fields which you include 
in the event registration process. If your site uses Profile(s) which include custom fields, 
make sure the role(s) that need to access these Profiles have this permission. 

Now that you have reviewed all the basic configuration tasks, you're ready to begin exploring 
the ways in which you can record and use contact data. 

SYSTEM WORKFLOW TEMPLATES 

Review and modify the templates used for system-generated emails, including contribution 
receipts and event registration confirmations. 
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11. THE NAVIGATION MENU AND 
DASHBOARD 

This is a brief overview of CiviCRM's Dashboard (home page) and the Navigation Menu that is 
available for people working in CiviCRM. This chapter will give a description of the Navigation 
Menu and Dashboard and explain their use. 

THE NAVIGATION MENU 



Home Search... Contacts Contributions Events Mailing 



The navigation menu is a small bar at the top of every "back office" page of CiviCRM that 
provides access to nearly every function of CiviCRM. The menu is broadly organized into 
headings by individual CiviComponents (such as Contributions, Events and Mailings), with a few 
exceptions for Search and Administer, both of which cover all of the enabled CiviComponents. 



Contacts Contributions Events Mailings Memberships 



Find Contacts - 
Full-text Search 



Search Builder 



Find Contributions 
Find Mailings 
Find Members 
Find Participants 
Find Activities 
Custom Searches... 



ummary 



x - Activities 

* Type $ Subjec 

Phone how was 
Call the 

meeting 



The menu also features a Quick search field for finding contacts. Typing any part of a 
contact's name or email address into the Quick search field will pull down a list of possible 
matches that you can click on to go directly to the contact's summary page: 



Fraddie Samuels'; home 



3nes, 5am :: 46367S97 



Jones, Sam 

Parker, Sandy 

Sam Samuels's home :: 

39694937 

Samuels, Bill ;: 68842635 

Samuels, Fraddie 

Samuels, Milan 



IE 



L 



You can modify the menu by clicking on "Administer -> Customize -> Navigation Menu" and 
then adding or re-arranging menu items on the screen. Remember that changes you make to 
the menu will be seen by everyone with appropriate permissions, who sees the menu, for 
better or for worse ;) - so be careful when modifying the menu. 

THE DASHBOARD 
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When you first log into to CiviCRM the first page that you will see is the Dashboard (CiviCRM 
Home). The Dashboard allows you to see important information about your site and CiviCRM 
by displaying a series of "Dashlets." A Dashlet is a snippet of information about a part of 
CiviCRM: many Dashlets come with CiviCRM by default or you or your administrator can create 
Dashlets that are specific to your organization's needs. Some examples of Dashlets that 
come with CiviCRM are: 

• Donor Report - a bar graph of the amount of total contributions per month for the last 
five months. 

• Activities - a list of recent activities that have been recorded by CiviCRM (this could 
include emails sent to constituents, donations that have been made, or meetings that 
have been scheduled in CiviCRM) 

• Membership Report - a table summarizing information about Members tracked by 
CiviCRM broken out by month. This includes the number of Members of each type total 
amounts of payments made and the number of contributions made, among other things. 



CiviCRM Home 



f Configure Your Dashboard 



(J) Refresh Dashboard Data 



» Donor Report (Summary) x 

Monthly Contribution Summa 




Month 



■» Activities 
* Type * Subject * Added By 



P x 



With P 

T 



Phone how was 
Call the 

meeting 



josue@progressiyetech.org Yadav, 
John 





€= =3 ^*+H 


■» Membership Report (Summary) p x 


Month Membership Member Total Contrit 
Beginning Type Count Payments Count 

Made 


March 2009 Student 


i 


$ 0.00 




SubTotal 


i 


$ 0.00 




April 2009 General 


l 


$ 0.00 





You can add these Dashlets to your CiviCRM Dashboard by clicking on the "Configure Your 
Dashboard" button from there, you will see a list of Dashlets that can be dragged into the 
right or left column. 
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CiviCRM Home 



Available dashboard elements - dashlets - are displayed in the dark gray top bar. Drag and 
drop dashlets onto the left or right columns below to add them to your dashboard. Changes 
are automatically saved. Click 'Done' to return to the normal dashboard view. P 



Available Dashlets 



[ 



Event Income Report (Summary) * 



Left Column 



Right Column 



Donor Report 
(Summary) 



Activities 

Membership Report 
(Summary) * 







Access keys: ^ 



Clicking the "Done" button will allow save the Dashlets to your dashboard. From now on, you 
will be able to see updates to the status of your Dashlets every time you log in (if you'd like 
to check and see any changes that have occurred more recently, you can always click the 
"Refresh Dashboard Data" button - this will reload each Dashlet and pull in any new 
information). 
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12. 



CONTACTS 



CiviCRM uses contact records as central hubs for data about your organization's contacts. 
There are three distinct contact types defined in CiviCRM, each suited to a common type of 
contact your organization may want to track: 

• Individual - any person your organization wants to keep a record of. 

• Organization - this could be another non-profit, a company, a chapter of your 
organization, or a committee. You will generally want to create at least one contact of 
the Organization type to represent your organization. This is particularly useful when 
you are configuring memberships. 

• Household - a family or group of people who share a physical location. 

CiviCRM provides different fields for each contact type, in accordance with the different kinds 
of data you will probably want to track. For example, gender only applies to individuals, not 
organizations or households, so the "gender" field is only available for "Individual" contact types 
and subtypes. You can also define additional data that you want to collect and apply it to only 
one type. You could choose to create a custom data field to record the Chairperson or CEO's 
name and only apply this field to organizations. 

ADDING A CONTACT 

The simplest way to add a single contact to CiviCRM is to use the Navigation Menu at the top 
of any non-public page. To create a new Individual you can click "Contacts -> New Individual": 



Contributions Events Mailings Memberships 
New Student 



ik Sprint Sa 



^access,,. 



Mew Individual 




New Organ izatic 
New Activity 
New Email 


" 



Import 
Import. 
New Household 
f Co New Group 

Manage Groups 
New Tag 
Manage T< 



New Parent 



New Funder 

New Media Contact 



New Elected Official 



Binary 



x » Activities 
* Type * Su 



Note that the "Contacts" menu item allows you to create every kind of contact and contact 
sub-type. 

Clicking on "New Individual" will bring you to the "New Individual" form. All of the contact 
creation forms are similarly organized, with basic information (name/email etc..) at the top of 
the form, and more specific fields below grouped by type or subject in accordions (these 
include address fields, communications preferences and any custom fields that you have added 
for the contact type.) 

You can fill out as many of these fields as you like, however it's recommended that you have 
at least a name and email address (it is only require that you have first and last name OR 
email address.) Remember that there is no difference between the contact add and edit 
screens, so you can always go back and make changes as needed. 

Once you are done filling out the form, you can click "Save" to go to the Contact Screen, 
"Save and New" to save the contact and clear the form so that you can add another, or 
"Cancel" to disgard your work and return to the CiviCRM Dashboard. 
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THE CONTACT SCREEN 



The best way to get to grips with contact management is to have a look around the various 
screens that are used to store and display information about contacts. 

You can find a contact from the CiviCRM home page by entering part of their name or e-mail 
address in the quick search box. Or leave it blank and hit the Search button to find all the 
contacts in your database. Below is a search for "sa" that has returned our friend Sam Jones 
from the example above. 




Jones, Sam 

Parker, Sandy 

Sam Samuels's home :: 

39694937 

Samuels, Bill :: 68S42635 

Samuels, Fraddie 

Samuels, Milan 



CONTACT ACTIONS RIBBON 

Across the top of all contact records is an "Actions Ribbon" with a variety of buttons that 
allow you to perform actions that related to the current contact. Clicking the "Actions" button 
will produce a dropdown with a number of actions that can be performed on this contact. For 
example you could add a note to this contact, or record a new activity. 

g sam@jones.com 

Your Individual contact record has been saved. 



ontact Dashboard 



S, Print Summary 



Add Contribution 
Register for Event 
Add Membership 
Add Case 
Add Relationship 
Add Note 



Add Activity: 



Memberships o Events 2 Activities 6 Cases o Rel 
■Change Log 1 Voter Info Grassroots InFo 

hdividual 
lolunteer 



L 



new activity ■ 



sam(5 jones. com 



Home Phone 
Home Mobile 



46363 

E757BI 



If you wish to change any information about this contact, you can go to the editing screen by 
clicking the "Edit" button. There is also a button to Delete the contact. If you with to print out 
the contact's details choose the "Print" button to take you to a print-friendly view of this 
contact's information. The "vCard" button, will bring the contact's details into your email client 
(you shouldn't do this if you want your emails to this person to be recorded in CiviCRM). The 
"Contact Dashboard" button will take you to the "Contact Dashboard" a screen that allows 
users to view and modify their own group subscriptions, and see the history of their own 
contributions, memberships and event registrations. 

If you're using CiviCRM in conjunction with Drupal or Joomla, you may also see a link to "View 
User Record." This link is shown when the contact is a registered user of your site. It links to a 
CMS-specific User Account screen. 
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CONTACT TABS 

A list of tabs underneath the Actions Ribbon break up the contact's information into related 
chunks. We are going to cover the contact summary tab here in some depth, and then look at 
other tabs that may be available to you based on your configuration. 

If you think that some of the tabs are not useful and will not be used in your deployment, you 
can make changes (disable or enable chosen tabs) from "Administer -> Global Settings -> Site 
Preferences." If you don't see some of the tabs described below, you might need to enable 
them. Some tabs are dependent on the components that are enabled in your installation. For 
example, the Contributions tab will be hidden if the CiviContribute component is disabled. 

SUMMARY TAB 



The summary tab gives you an overview of information about your contact. Here you will find 
names, addresses and contact details. The information on this page appears fairly 
straightforward, but take a closer look and you will find some pretty clever stuff is going on. 

$ Kurund Hi s 



© Contact Dashboard 



a Print Summary 



Summary Contributions Memberships 1 Events Activities i Cases Relationships 
Groups 1 Notes Tags □ Change Log 1 Voter Info Grassroots Info o 
School Information o 



Contact Type 



Individual 



Home Email 
Home Address 



1234 Street Name 
Deepak Town, NY 
10013 
United States 



▼ Additional Address Info 

Landmark 



Privacy 

Preferred Method (s) 

Email Format 



Both 



Email Greeting 

Postal Greeting 



Gender 

Date of birth 

Age 

Ethnicity 

Primary Language 

Secondary Language 

Kids? 

Addressee 



Communication Details 



Constituent Info - Individuals 



CiviCRM includes a complete set of fields "out-of-the-box" to store basic contact information. 
They are usually referred to as built-in fields. They include: 
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• Name fields 

• Job title and employer 

• Phone numbers, email address(es) and instant messenger screen names 

• One or more mailing addresses - If 'Map this Address' is showing above the address, you 
can bring up a map (either using Google Maps or Yahoo Maps, depending on your 
system's configuration) showing you where this person lives. If it doesn't show on your 
screen, this feature hasn't yet been configured for your site. You can add map support 
from Administer CiviCRM -> Global Settings -> Mapping and Geocoding. 

• Basic demographics (gender and birth date) 

Note one small but significant feature of the summary screen - if you have a number of long 
sets of fields, it may become useful to collapse some of them. Below "Communication 
Details" has been collapsed, while "Constituent Info - Individuals" is expanded. Some field sets 
can be set to be expanded or collapsed by default. This happens for example when a contact 
has more than one location entered. The first one is shown by default, the rest of them will 
be collapsed. Clicking on the header will toggle the status of the field set. 



► Communication Details 



•r Constituent Info- Individuals 

Constituent Type Donor 

Other Name 
Staff Responsible 
Date Started 
How Started 



Name Fields 

Each contact's name can include the following fields: Prefix, First, Middle and Last Names, 
Suffix and Nickname. You don't have to use all of them, but they are available in case you 
want to store all of this information. 

If you wish to record a prefix such as "Mr", "Ms" or "Dr" for your contact you can do so using 
the dropdown box on the edit screen. If there are other prefixes you need to use such as "Sir" 
or "Father", you can add these to the dropdown list in "Administer CiviCRM -> Option Lists -> 
Individual Prefixes (Ms, Mr...)". The same applies to name suffixes. 

Locations 

A location is a group of address related fields consisting of phone, email and postal address 
field groups. 

CiviCRM can hold more than one location for a contact. For example, a person may have a 
home address, a billing address and a work address and we need to record these in separate 
"locations." One of these locations will be marked as "Primary". It will be used for any postal 
mailings that you do. You can explicitly choose which location will be primary for a particular 
person, or let it default to the first one entered. If a person pays you by credit card the 
details used for Billing Address in credit card payments will be stored in the Billing location 
for the contact. You can specify the maximum number of locations a contact may have from 
"Administer CiviCRM -> Global Settings -> Address Settings." The default for this setting is 1. 
You will need to modify it if you plan on recording multiple addresses for some contacts. 

You can also store multiple phone numbers and email addresses for each location. One of 
these email addresses can be explicitly marked as the address which receives all bulk mailings 
(e.g. emails your organization sends using the CiviMail component). 

RELATIONSHIPS TAB 
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Relationships are basically "connections" between contact records in your database. Each such 
connection can be named to describe the nature of the connection, and a contact may have 
many relationships to other contacts in the database. Below you can see a list of "Current 
relationships" as well as a list of "Inactive relationships." Contacts can have relationships with 
set start and end dates for example, a contact could have a relationship "Committee Chair" to 
an organization for a one year period. In order to track past Committee Chairs, you can keep 
a record of the contact having an inactive Committee Chair relationship. 
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± Relationship 




* City 


t Stat 


e/Prov * Phone * End Date 




Household Member 
of 


Paula Reynolds's 
home 


Detroit 


MI 


60117249 April 20th, 
2010 


View 



Another example of a relationship that might be tracked in CiviCRM is the Employee-Employer 
relationship. Richard is an employee of the organization Acme Org, and you want to store this 
information in the database you can set Richard to be an "Employee of" Acme Org. You do 
this by creating a relationship between Richard and his employer. Once you do this, you will be 
able to see this connection from both Richard's and Acme Org's records. 

The Employee / Employer relationship is a special one. If you look at the Summary tab again 
you can see that the Current Employer field shows the name of the employer. This name is a 
link to the "ABC Org" contact record. Entering in an Employer in this field is a shortcut way to 
define an employment relationship. Whenever you fill in the Current Employer field a record 
with a matching name will be looked up and the appropriate relationship will be created. If no 
record for this organization exists one will be added before creating the relationship. 

The Household Member relationship is used for connecting individuals with households. When 
editing a contact, you can opt to "Use household address" - check this option if you want to 
use a shared household address for this contact. You can either select an existing household, 
or to create a new one just enter the name of desired household, select the same from drop 
down and press enter. When you have opted to use a household address for a contact - a link 
to the Household's contact record will be displayed along with the usual address information in 
the contact summary tab. Using a household address for a contact also automatically creates 
the Household Member relationship between the contact and household. 

Apart from the two special relationship types, you can create and register any other type of 
relationship. The Relationships tab shows all of a contact's existing relationships with other 
contacts (individuals, households or organizations in the database). If you want to create a new 
type of relationship, go to "Administer CiviCRM -> Option Lists -> Relationship Types." 

Additional powerful characteristics of relationships include the ability to set a start and end 
date, or disable them manually if they are not valid anymore. This means, that you can store 
the history of relationships in your contact records. 
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Relationships can be also extended with custom fields if you need to store additional 
information for them. 

ACTIVITIES TAB 

The Activities tab does two things. First, it displays all your interactions with the contact over 
time. This includes all CiviCRM's built-in activities like event attendance, contributions, 
membership sign-up and renewal, phone calls, emails and user-defined activities. Second, it 
allows you to record activities with contacts. Clicking on the icons at the top of the screen 
(Send an Email, Meeting, Phone call) will bring up a screen where you can enter those details. 
This tab can also be used to record any custom activities that you've defined for your CiviCRM 
installation from "Administer CiviCRM -> Option Lists -> Activity Types." The ability to define 
custom activity types, and extend them with custom fields provides a powerful tool for 
tracking a wide variety of organization activities. You could choose to track activities such as 
press releases, press conferences, site visits or voluntary work. 

Activities are a great way to store interactions that happen at a specific time, or that link 
specific people. If it is important for you to know who at your organisation carried out a task, 
record it as an activity. Another advantage of activities is that they record when something 
has happened, which is useful if you need to report on the volume of activities performed 
during a specific time period. You can record an activity between a given contact and multiple 
other contacts by adding as many contacts as you like in the "With Contact" field on the "Add 
Activity" form. 

Activities usually have their status set to "Completed" or "Scheduled," however you may add 
other types of activity status as appropriate for your organization. 
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CONTRIBUTIONS TAB 
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The Contribution Tab shows any financial contributions made by the contact whose details you 
are viewing, as well as a summary of the contribution activity of the contact (total amount of 
contributions over time, total number of contributions, and average amount of contributions). 
The Contributions tab also allows you to record off-line contributions using the "Record 
Contribution" button, or record a credit card transaction on behalf of the contact (useful if 
recording a contribution over the phone) using the "Submit Credit Card Contribution" button. 
Both of these buttons lead to forms that allow you to select contribution type in addition to 
the normal contribution information collected from public contribution pages. 
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MEMBERSHIPS TAB 

This tab displays the memberships a contact has signed up for. From this tab you are able to 
add and memberships and submit credit card payments for memberships that require 
donations. You can also renew or delete memberships from the "more" link on each 
membership in the contact's existing memberships. 



Summary Contributions l Memberships l Events 2 Activities 8 Cases o 
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Click Add Membership to record a new membership. Click Submit Credit Card Membership to 
process a Membership on behalf of the member using their credit card. 
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EVENTS TAB 
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The Events Tab displays events related to this contact, whether they are events the contact 
has registered for, attended, volunteered at or any other of the user configurable event 
statuses. Note that the related payment showed up on the Contributions Tab (above image) in 
the top row. From this page you can register the contact for an event, or register the contact 
for an event requiring a payment (using the "Submit Credit Card Event Registration" button). 
Note that you can also modify the event information as it relates to the contact (for example, 
to switch the contact's event status from "registered" to "attended"). 

Summary Contributions l Memberships l Events 2 Activities 8 Cases o 
Relationships 4 Groups i Notes l Tags l Change Log o Voter Info D Grassroots Info o 
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This page lists all event registrations for Mrs Bruce M Jones Sr since inception. Click Add 
Event Registration to register this contact for an event. Click Submit Credit Card Event 
Registration to process a new New Registration on behalf of the participant using their 
credit card. 
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GROUPS TAB 



The Groups Tab shows the groups that the contact is a member of. Groups can be used in a 
variety of ways including mailing lists and permissioning (ACLs). Note that the "status" column 
displays who has added the contact to the group. Whether users can add themselves to a 
group is one of the settings you can configure when creating a group. When you set a group's 
visibility to "Public Listings" users can join via Profile forms. You may want to familiarize 
yourself with the discussion on using Profiles for mailing list sign-ups covered in a later 
section. Also note that you can see a history of groups the contact has un-subscribed or 
been removed from. 
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NOTES TAB 
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The Notes Tab is a place where you can record random bits of information about a contact. 
Generally you would use custom fields for information you plan to collect about your contacts, 
but in some cases it may be useful to record additional, ad-hoc notes about people. Since 
information stored in notes is unstructured, you should be careful about using the Notes Tab, 
unless you know that you or other people using your CiviCRM implementation will remember 
to look at that tab. When creating a Note both the subject and the content are free-text 
fields (i.e. the subject field does not have to be chosen from pre-defined options). 
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TAGS TAB 

Tags are one way of categorizing contacts in your database. (Other methods are Custom Data 
and Groups). You can configure which tags you wish to use for your organization. You can 
search on tags and create Smart Groups based on them. The tags next to "Keywords" are 
part of the "Keywords" Tagset. A Tagset is a grouping of tags that you can create that are 
separate from the regular grouping of tags. Tagsets are not-hierarchical, and you can create 
a new tag in a tagset simply by typing a new tag into the field, tags that match what you type 
will also show up as a list which you can select from. 

Summary Contributions o Pledges o Memberships o Events o Activities o 
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CHANGE LOG TAB 

This tab gives limited information about changes made to a contact record. It shows the 
change date and who made the change, but not what was changed. 
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Change Log: 

Changed By Change Date 

§ kurund@web.com April 27th, 2010 1:44 PM 

Q bob@scout.com April 27th, 2010 1:44 PM 

CONTROLLING THE CONTACT SCREENS 

After working with the contact editing and summary screens for a while, you may realize that 
there are sections and / or fields that aren't useful for your organization. The good news is 
that you can easily hide some fields and sections. For example, if your organization doesn't 
need to store demographics information - you can remove it by configuring Site Preferences: 

• Login to CiviCRM using account with Administer CiviCRM privileges, 

• Navigate to 'Administer CiviCRM -> Global Settings -> Site Preferences", 

• Un-check the Demographics box under Editing Contacts, 

• Hit Save button. 

Similarly, if you want to remove (or add) fields in the postal address section: 

• Navigate to 'Administer CiviCRM -> Global Settings -> Address Settings" 

• Check or un-check fields under Address Editing 

• Hit Save button. 
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13. 



TAGS AND GROUPS 



Tags and groups are two key methods of organizing data in CiviCRM. Both allow for powerful 
segmentation and searching of your database when used properly. 

Since both tags and groups are methods of categorization, it can be confusing to determine 
whether a tag or a group is more appropriate in a given situation. Each comes with its own 
workflow and set of functionality, both of which might help you determine what you need at a 
given moment. 

It can also be good to have a conceptual understanding of the differences between the two. 
Though there are different takes on how the two should be used, a common philosophy is that 
tags should be used for descriptive categories and groups should be used for grouping people 
within a cohesive entity that functions or will be treated as such. From this perspective, things 
like volunteer, ally organization, vegetarian, and musician would be tags with which you could 
categorize contacts and Volunteer Committee, Allied Organizations Coalition, Vegetarian 
Newsletter, and This Awesome Band With A Bad Name would be groups to which you could add 
contacts. 

TAGS 

Tags are used to categorize contacts, activities, and cases in CiviCRM. You can create as 
many tags as needed to classify the contacts in your database, though it is advisable to avoid 
duplicating existing tags or adding too many tags that aren't really necessary. It can be useful 
to create a standard process for creating and using tags within your organization to avoid 
these problems. 

Viewing, Creating, and Editing Tags 

Tags can be viewed by going to the Contacts -> Manage Tags (Categories) in the navigation 
menu. 

A tag can be edited or deleted using the respective links in its row. New tags can be created 
by clicking the "Add Tag" button on the Manage Tags (Categories) screen or by going to 
Contacts -> New Tag in the navigation menu. 
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Each tag should have a clear and unique Name and an explanatory Description to help users 
understand the tag's purpose. Tags can be structured hierarchically and designated as subtags 
of an existing tag by selecting the Parent Tag from the dropdown list. 

Tags can be designated for use for contacts, activities, and/or cases. If a tag is designated for 
use for contacts, it will be available for all contact types and subtypes; tags cannot be 
specifically designated for use for only one type of contact. 

Tags are a pretty flexible tool and every user can create more if needed. However, you can 
lock some very important tags that if you design them reserved. They cannot be modified or 
deleted by users who do not have the "administer reserved tags" permission (this permission 
is available in Drupal only). 
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Tags can be assigned to contacts, activities, and cases while: 

• creating or editing the record 

• from the Contact Summary Tags tab 

• by using the Tag Contacts batch action after conducting a search. 

You can also use the first two methods to remove tags as well. 
Tag Sets 

Tag sets allow you to create free tagging taxonomies within which users can add their own 
tags on the fly, without having to access the Manage tags page described above. 

Tag sets are created by going to Contacts -> Manage Tags (Categories) in the navigation 
menu and clicking the Add Tag Set button. Tag sets are configured identically to regular tags. 
However, they function quite differently. When you create a new tag set, it creates a new 
field on the edit pages of the entities activities or cases as well as in the Tags tab for 
contacts. 

This is an tokenizing autocomplete field; as you begin to type, CiviCRM looks for matching tags 
in this tag set and displays any matches below the field. You can select an existing tag or 
create a new one by typing the entire tag and pressing the Enter key. The tag will then appear 
within the field in a box; clicking on the X will untag the entity (contact, case or activity) that 
you are editing. 

Tags created within a tag set can be viewed and edited from the normal Contacts -> Manage 
Tags (Categories) list. However, tags created within a tag set will only be available within that 
particular tag set. 

GROUPS 

Groups are an incredibly important feature within CiviCRM. In addition to their fundamental use 
as collections of contacts that have something in common, they play a critical role in CiviMail, 
Profiles and can be used to set up advanced access rights (on drupal). Well-defined groups are 
one of the most important tools available when segmenting your CiviCRM contact database. 

There are two kinds of Groups - Regular Groups and Smart Groups. 

Regular Groups allow you manually place contacts into a group. For example, you can 
manually assign your organization's board members to a "Board of Directors" regular group. 
You can then easily send board-related emails to each person who is a member of the "Board 
of Directors" group without having to search through CiviCRM and select each member one- 
by-one for the mailing. 

Smart Groups are automatically populated groups that are configured to include contacts 
that share a certain set of characteristics or activities. As contacts are added or edited 
CiviCRM automatically checks them and adds them to Smart Groups if they meet the 
characteristics that you have configured. For example, you can create a Smart Group for 
"2010 Contributors from California" that includes contacts who have made a contribution in 
the year 2010 (an activity) and have an address in California (a characteristic.) When new 
contacts located in California make a contribution in 2010, they are automatically added to this 
group. In another example you can create a Smart Group of all donors who have not yet been 
sent a thank-you letter. As you send your letters, the donors receiving them will automatically 
leave the smart group, allowing you to always have an accurate list to work from. 

Group settings and functionality 

Each group should have a clear, easily understandable group Name and a Description of the 
group and its purpose, both of which will allow users to quickly figure out what particular 
groups are for when working in different contexts (e.g. CiviMail.) This clarity and specificity is 
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especially important once your organization has amassed many different groups. If a group is 
created for a specific person within your organisation, it is a good idea to mention in the 
description who the "owner" of the group is, to be able to check in the future if this group is 
still used or if it can be deleted. 

Groups can be assigned the following types: 

• Mailing List is used if you plan to use this group as a mailing list in CiviMail. This group 
type is available for both Regular and Smart Groups. 

• Access Control (Drupal only) is used to assign CiviCRM access permissions to a set of 
contacts. Only Regular Groups can be assigned the Access Control group type. 

Visibility determines permissions for joining and removing contacts from groups. Select "User 
and User Admin Only"if membership in this group is controlled only by authorized CiviCRM 
users. Select "Public Pages" if you want to allow contacts to join and remove themselves from 
this group via Registration and Account Profile forms. 

Some organizations find it useful to create a hierarchy of groups. In CiviCRM, this is done by 
creating one or more Parent Groups and then assigning other groups to them. When a user 
sends a mailing to a parent group or searches for contacts in a parent group, all contacts in 
the associated child groups are automatically included. 

EXAMPLE: An organization that has a national office and 5 regional offices puts constituents in 
each region into their own group. Then they create a "National" group which is assigned as the 
parent group for all regional groups. The national office can now send mailings to the National 
group, knowing that all contacts in the regional groups that are children of the National group 
will be included. 

Adding and Removing Contacts 

You can add contacts to groups in multiple ways: 

• through the Tags and Groups section of the Contact Details edit screen; 

• through a contact's Groups tab; 

• by using the "Add Contacts to Group" batch action after conducting a search; 

• and by clicking a group's Contacts link in Navigation Menu -> Contacts -> Manage 
Groups. 

The first two methods also allow you to remove individual contacts from a group; the last two 
methods allow you to add multiple contacts to groups at once. 

Individual contacts can be added to a Group either in the Contact edit screen or via the 
Groups Tab. Multiple contacts can be added to a group at once by conducting a search, and 
then selecting Add Contacts to a Group using the More Actions menu. The second way allows 
you to add multiple contacts to a group by going to Manage Groups, selecting Members for the 
relevant Group and then using the Add Members to this Group option at the top of the 
screen. 

Contacts can also be added to a group as a result of filling out a Profile (see below.) 

Managing Groups 

To view and manage all groups, go to Navigation Menu -> Contacts -> Manage Groups. 
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You can use the Find Groups form at the top of the Manage Groups screen to search for 
groups by name, type, visibility, and whether the group is enabled or disabled. You can also 
scroll or browse through the list of groups further down the Manage Groups screen. This list 
includes both regular and smart groups. You can add contacts to a group by clicking the 
Contacts link in the group's row, edit the group by clicking the Settings link, and disable or 
delete a group using the links in the "more" pop-up menu. 

Group IDs 

CiviCRM assigns a unique numeric ID to each group. These group IDs can be used for a variety 
of operations; for example, the group ID can be used to define a URL for group sign-ups. You 
can find a group's ID by checking the ID column in the tabled list of groups at Navigation 
Menu -> Contacts -> Manage Groups. 

Finding contacts in a group 

The Contacts page for each group includes a form for finding contacts within the group. You 
can search contacts within a group by name, email address, contact type, group status 
(added, removed, or pending), and tags. 
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Creating and Managing Smart Groups 

Smart groups are created by conducting a search (either quick or advanced) based on the 
criteria you'd like to use to determine who is automatically added to or removed from the 
smart group, then using the "New Smart Group" batch action in the "- actions -" menu on the 
search results page. The smart group creation page is similar to the regular group addition 
page except that it displays the smart group criteria at the top. 

Though smart groups are automatically maintained by CiviCRM based on the criteria you've 
set, you can manually add or remove contacts from the smart group whether or not they 
match that criteria. Wpecific individuals can be added or removed from them. For example, if 
someone unsubscribes from a mailing that is based on a smart group, they will be recorded as 
removed from the group even if they still meet that smart group's search criteria. Similarly, 
you can manually add a specific individual to a Smart Group. For example, you can add 
someone who is moving away from a city to that city's newsletter smart group so that they 
continue to receive the newsletter despite their address not matching the criteria for the 
smart group. 

To manage smart groups, go to Navigation Menu -> Contacts -> Manage Groups and click 
the Settings link for your chosen group. Smart group management pages include links for 
manually adding contacts and editing the smart group's criteria. When you edit a smart group's 
criteria CiviCRM will update the members in the group and future members will be 
automatically added according to the new criteria. 

Using Groups in a Search 

When using Advanced Search, if you select several groups in the Group list near the top, it will 
treat the search as an OR search, and return results for contacts who are in any of the 
Groups you select. If you want to find contacts who belong to all of the selected groups, you 
will need to use Search Builder. 
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There is also a very useful built-in custom search, "Include/Exclude Contacts in a Group/Tag," 
that enables you to find contacts who are in one group but not in another, which you can find 
in Navigation Menu -> Search -> Custom Searches. 
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Groups and ACL (Drupal Only) 

Access Control Lists (ACL) provide finer grained permissioning than what is available through 
Drupal's Permissions and Roles. Setting up ACLs requires a good understanding of the concept, 
which is thoroughly explained in the online CiviCRM Documentation here: 
http://wiki.civicrm.org/confluence/display/CRMDOC/Access-l-Control 

As with many processes, the key is to make sure you have assembled all the parts before 
you try to join them together. In this case you must set up the required Groups, Custom 
Data Groups, Profiles and Roles before you can use them in ACL. 

Groups and Organic Groups (Drupal Only) 

The Organic Groups CiviCRM module (http://drupal.org/proiect/og_civicrm) integrates organic 
groups from a Drupal site with CiviCRM groups. This is useful for groups that require Organic 
Group functionality on your website but also need to be tracked within CiviCRM. Once an 
organic group of Drupal users is integrated into CiviCRM, the Drupal group can be used for 
mailings, tracking address information, tracking activities or anything else you normally do with 
CiviCRM contacts. 

Once the Organic Groups CiviCRM module is installed and enabled in Drupal it automatically 
creates two CiviCRM groups for each existing Drupal Organic Group: 

• A normal group containing a contact record for each corresponding user who is part of 
an Organic Group. This group is assigned the same name as the linked Organic Group. 

• An access control group containing the contact record of the administrator of the 
corresponding Organic Group. This gives the OG group admin the ability to view and edit 
members of their group in CiviCRM. 
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The groups are synchronized one way only, from the Drupal organic groups to CiviCRM groups. 
When a new user is added to or signs up for an organic group, they are automatically added to 
the corresponding CiviCRM group. If they leave the organic group then they are removed from 
the CiviCRM group. If an organic group is deleted the CiviCRM group is deleted. However, the 
reverse of each of this situations is not true; a contact added to the CiviCRM group will not 
appear in the Drupal organic group, a contact removed from the CiviCRM group will still remain 
in the Drupal organic group, and if ou delete the CiviCRM group, the Drupal organic group will 
still remain. Therefore, this integration is meant to be used when you administer the group 
from the Drupal side. 

When to Use Tags Versus Groups 

This is a common question on any project, and the philosophy described in the introduction of 
this chapter is a guideline, but rules might need to be bent based on how you intend to use 
your contact segmentation. 

One interesting benefit of having both groups and tags is that the search "AND" them. For 
instance, if you have journalists, volunteers and members as groups and use tags to identify 
topics of interests, eg. development, art and history, you can fetch all the journalists that are 
interested in art or development, all the volunteers or members that are interested in history, 
or any combination. 

Beside that, groups have some features that tags don't 

• integrated into several other CiviCRM functions (most notably CiviMail), 

• smart groups automatically based on characteristics of contacts, a feature not provided 
by tags. 

• can be associated to Drupal groups. 

On the other hand, tags can be used on contacts, activities, and cases, whereas groups can be 
used only to group contacts. 
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14. 



SEARCHES 

This chapter covers different ways to finding contacts in CiviCRM. Finding contacts is a pretty 
core function in CiviCRM as is the 'search - action' work flow, so most if not all users of 
CiviCRM will find this chapter helpful. We start off with some simple searches and then move 
on to more advanced techniques. CiviCRM beginners should be familiar with Quick search, 
advanced search and the component searches. More advanced users should look at the 
reports, custom searches and search builder. 

There are three main reasons to search: 

• to find a specific contact 

• to find contacts that meet certain criteria and then perform an action (the 'search- 
action' workflow) 

• as a form of adhoc reporting 

FINDING A CONTACT 

The easiest way to find a specific contact, if you know part of their name or email address is 
to use the quick search box that appears at the top left of the screen. Matching contacts will 
appear below the box. For example, 'peter' will match 

• people who's first or last name is Peter 

• people who have Peter appearing as part of their name, e.g. 'Mary Peterson' 

• organizations with Peter in their name, for example 'Petersfield Community Centre' 

You don't need to type the full name of the person - just the first few letters. 
I 



Peterson, Maiy 



If you don't know their name, but you do know some other details about the contact, try 
using advanced search to search on specific criteria about that contact. 

FINDING CONTACTS MATCHING CERTAIN CRITERIA 

A common work flow in CiviCRM is to find contacts that meet certain criteria and then 
perform an action with them. For example to find all contacts in the advisory group and invite 
them to a meeting, to find all members who have recently expired and invite them to renew 
or find all under 25s in a specific location and send them an email about an upcoming event 
nearby. 

ADVANCED SEARCH 

Advanced Search allows you to choose from a broad range of information that you hold about 
contacts. 

You can combine certain criteria to perform specific searches. For example, you could find 'all 
contacts in Venezuala', 'all advisory group members' or all advisory group members in 
Venezuela'. 
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The different criteria in are grouped into an accordian. Different sections in the accordian refer 
to different types of data about the contact that you can search on, for example, their 
address data, their notes, and different information that comes from different components. 

You will also see several gray bars on this screen. If you click on a gray bar it expands to 
reveal more options. For example, if you wanted to search for all people in your database 
between 16 and 18 years old you would click on the "Demographics" bar and select the Birth 
Date range you are interested in. 
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Combining search criteria 

The default way of combining different fields is by 'ANDing'. For example, selecting the tag is 
'major donor' and the country is 'Mexico' the search will return major donors from Mexico. 

Within fields, the optioned are combined by 'ORing', for example contacts that live in Mexico 
and the United States. 

Modifying search columns 

Advanced searches also allow you to use to change the columns that are displayed in your 
search results. The default columns are Name, Street Address, City, State, Postal Code, 
Country, Email and Phone. If you want to display a different set of columns (perhaps including 
a custom field and removing the Country column) you can create a Profile with the "Search 
Results" option selected. Make sure that the fields in this Profile are set to "Public User Pages 
and Listings" visibility, and are marked as "Results Columns". The Profile will appear in the 
"Search Views" dropdown in the upper right corner of the form - as shown below. 
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Combining this feature with the "Batch Update via Profile" action provides a powerful method 
of viewing and updating a specific set of fields for a batch of contact records. 

You may want to familiarize yourself with the steps for creating Profiles which are described in 
detail in another section. 



You can also view a special "Summary Profile" in search results by hovering over the contact 
icon: 
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THE "SEARCH-ACTION" WORKFLOW 

Once you have your search results you can perform a number of actions. An actions box 
appears above the menu. You can either select all records, or select specific records and then 
carry out an action with them. Different actions are covered in more detail in 'daily tasks'. 
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Some of the most commonly used actions are "Add Contacts to Group", "Export Contacts", 
create and print "Mailing Labels" and "Map Contacts". 

For example, you might want to view the locations of a number of contacts on a map to help 
you plan a route for home visits. To do this, mark the contacts you are interested in and then 
select "Map Contacts" 

THE WILDCARD (%) 



Understanding wildcards really opens up your options when you want to search. In CiviCRM 
when we refer to a wildcard we are talking about the % symbol. You may be familiar with 
other symbols such as '*' from other applications. 

A wildcard is a symbol we use to mean 'any character' (letter or number or punctuation 
mark). It is most easily understood through examples. 

If we search on the first name 'Michael' we will find all the people with the first name 'Michael'. 
If, however, we search on 'Mich%' we might find 'Michelle', 'Michat', 'Micheal' and 'Michele'. This 
is really useful if we don't know how 'Michael's' name is spelled, or we think it might have been 
misspelled. Wildcards can be used before, after or even within words. For example, searching 
on 'Mich%el' will exclude 'Michat' and 'Micheal' but still shows 'Michelle', and 'Michael'. 

You can see that this search is not case sensitive. In other words even though we entered 
'mi%el' in lower case, it found people that had upper case Ms in their name. 

COMPONENT SEARCHING 

Most CiviCRM components have a component search (e.g. Find contributions, Find members, 
etc). These forms work in a similar way to advanced search with one important difference - 
the rows they return are not contacts. Find members returns memberships, Find Participants 
shows event registrations, Find contributions returns contributions etc. 

Each component search has it's own action list of actions. See the Component sections for 
more details. 

SEARCH BUILDER 

Advanced Search lets you choose from a wide range of criteria but it has its important 
limitation. In particular, most of the search criteria you select in advanced search are ANDed 
together. 

The Search Builder tool provides an alternative when you need to do a search using OR for 
some criteria. Continuing the example above, you can build a search for contacts who are born 
within a range of dates OR who are female. 

- Edit Search Criteria 
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Search Builder is intended for advanced users and requires you to use specific formats for 
your search values. Refer to the online documentation at 

http://wiki.civicrm.org/confluence/display/CRMDOC/Search+Builder before you try to create 
your own searches. 

REPORTING 

CiviReport allows creating reports from templates with specific display columns, filters and 
grouping rules. See Reporting section for more details. 

CUSTOM SEARCH 

Custom searches are designed to answer specific questions that can't be easily answered 
using Advanced search or search builder. A good example is the 'Include / Exclude Contacts in 
a Group / Tag' which, in combination with a previously run advanced search, allows you to find 
contacts that don't meet a certain criteria. Take a look at the list of available custom searches 
from CiviCRM -> Find Contacts -> Custom Searches. These have been written by 
members of the CiviCRM community to meet their own needs, and then contributed back to 
the community. It's worth spending some time exploring these searches as some of them may 
be useful to you, and they give you an idea of the sorts of things that are possible. 

It is possible to write your own custom searches, but you'll need to be comfortable with 
MySQL and PHP. See the section on extending CiviCRM for more information, and if you create 
a custom search you think would be useful for others, consider contributing it back to the 
community. 

When to use Custom Search? 

When using Advanced Search, if you select several groups in the Group list near the top, it will 
treat the search as an OR search, and return results for contacts who are in any of the 
Groups you select. If you want to find contacts who belong to all of the selected groups, you 
will need to use Search Builder. 

There is also a very useful built-in custom search, "Include/Exclude Contacts in a Group/Tag," 
that enables you to find contacts who are in one group but not in another, which you can find 
in Navigation Menu -> Search -> Custom Searches. 



85 



Edit Search Criteria 



[nc ud-c 



Administrators 


r 


Advisory Board 




bgm test 




case Resources 




Donations w/o Ehankvou 


R 



L « :fl,,: "'' j 



Exclude 
Groupfs) 



Adm nistrators 




Advisory Board 




bgm test 




Case Resources 




Donations w/o thankyou 


i 



fefJra'.f.ff^ 




Include 
Tag(s) 



Company 
Government Ent 


*¥ 


1 

[ 


Jack's Tag Set 
JackTag 

;-:..■,.'.. .. 





■MA^WJ 




EKClud* 



Company 

Government Entity 
Jack's Tag Set 
JackTag 
Keywords 



Id J, I. 1 . J 



86 



15 



IMPORTING DATA INTO CIVICRM 



Most organizations have data in sources external to CiviCRM, e.g. older database platforms, 
spreadsheets created on the fly for specific events or other purposes, and email address 
books. Since manually entering large amounts of data can be tedious, data that can be 
exported into a proper format can be imported en masse into CiviCRM. 

CONSIDERATIONS BEFORE IMPORTING 

If you have pre-existing data that you want to put into CiviCRM, you might find it useful to 
think of a process like moving your house or apartment. People often use moving as a chance 
to say, "Do we really need this? This stuff is too old; let's trash it and get some new stuff 
once we have moved in." 

To apply this metaphor to your data, look for fields that have no purpose, such as old 
organizational divisions that you've abandoned or office locations in a facility you no longer 
occupy. 

Some old data will have continuing value. For instance, one organization in a financial pinch 
decided to use an old list of founding donors who had not given money for many years. It 
turned out that these lapsed donors still had strong emotional ties to the organization that 
they had founded and they came to its financial rescue. In that case, saving old data was 
crucial. 

Moving to a new living space doesn't just provide an opportunity to evaluate what's really 
important to keep and what can be left behind; it also gives you a chance to clean up 
everything that you do decide to take with you. Just as you wouldn't pack up dusty picture 
frames and dirty dishes because that would make your nice new clean place as dirty as your 
old place, you'll want to clean up your data before moving it into CiviCRM so that you're 
starting off with as clean and useful a database as possible. 

In planning for a move to CiviCRM, prepare to spend a good amount of time looking at your old 
data; standardizing how different elements of contacts' records are stored (e.g. are states 
entered as NY or New York?); and deleting obvious duplicates, accidental entries, outdated or 
corrupted records. 

For many US-based organizations, an important element of cleaning your data is standardizing 
addresses to conform to the conventions defined by the United States Postal Service's 
Standards for Addresses. Standardizing how addresses are entered into CiviCRM will allow for 
more accurate search results when searching by address, as CiviCRM will parse addresses 
based on the USPS standards. To find out more about how Address Parsing is handled and 
used in CiviCRM, refer to the Address Parsing chapter of this book. When adding or editing 
contacts you will be entering or editing address elements including street number, street 
name, and Apt/Unit/Suite number according to these standards. 

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 
at http://pe.usps. com/cpim/ftp/pubs/Pub28/pub28,pdf,&nbsp : 

PREPARING TO IMPORT DATA 

Importing data is a reasonably involved process and it pays to be familiar with the concepts 
before you start your first import. You can import both core and custom data for contacts as 
well as data for event attendance, activities, memberships and contributions. This chapter will 
focus solely on the import process for contacts, though the processes are similar. 

There are two ways in which data can be imported: 
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• From CSV (comma separated value) files. Each column in your CSV file will map to a 
field in CiviCRM, so make sure you use a different column for every distinct bit of 
information. Most database and spreadsheet applications (e.g. OpenOffice Calc, Google 
Spreadsheets, Microsoft Excel) can create and manipulate CSV files. It is often easier to 
view and clean your data when it's in a CSV file than while it's still inside your old 
database. 

Note: depending on your country or region, your CSV files might actually be 
separated by semicolons, not commas. If so, you'll need to change the Import / Export 
Field Separator value in the CiviCRM Localization settings by going to Administer -> 
Configure -> Global Settings -> Localization in the navigation menu. 

• From another SQL or MySQL database held on the same server using an SQL query. 

If you do not have a clear understanding of your existing data and how it will map to CiviCRM 
fields, you will experience frustrations and problems when you try to import the data. Please 
read other sections of this CiviCRM Manual and visit the CiviCRM online documentation for 
more information: http://wiki.civicrm.org/confluence/display/CRMDOC/lmporting+Data 

You may encounter problems when running an import because every set of data has its own 
quirks. You can help avoid these problems by following these recommendations: 

• If your imports are timing out or taking too long, try splitting up imports into smaller 
batches. If you have sufficient permissions on your web server, you can also increase 
the memory _limit and max_execution_time values in php.ini. 

• Always test your data import with a small subset of your records. After importing the 
test set, visit the records within CiviCRM and ensure that the data was imported and 
functions as you expected. 

• Consider creating a test contact that has every attribute you've defined in your existing 
data set. Then import the contact and check results to ensure that CiviCRM correctly 
represents all the data labels and options from your old data. 

• When you map the columns or fields from your source data to CiviCRM fields during the 
import, CiviCRM can save this field mapping as an import map for future use, which is 
especially helpful if you will be importing multiple files with the same structure. To save 
an import map for future use, click the "Save this field mapping" checkbox at the 
bottom of the Match Fields screen of the import wizard and enter an appropriate name 
and description. To reuse a saved import map, select it from the Load Saved Field 
Mapping dropdown on the Choose Data Source screen (step 1) of the import wizard. 

• You can add all of the contacts imported in an import to new or existing groups or tags. 
Since all of the contacts in a single import will be given the same groups and tags, make 
sure that you only assign groups and tags that are applicable to every contact in the 
imported set. An import-specific use of this ability is to add contacts to a new group or 
tag that indicates what batch of imports the contacts were a part of, thereby allowing 
you to easily identify when a contact was imported and undo an entire import if 
necessary. 

• There is no way to automatically assign groups or tags on a contact-by-contact basis 
when conducting an import. To get around this limitation, you can import contacts in 
smaller, discrete batches in which all contacts share the same tags and groups. 
Alternatively you can create searchable custom data fields in CiviCRM that contain the 
groups and tags that you want to assign to imported contacts; after the import you can 
run searches on those fields and use the "Add Contacts to Group" or "Tag Contacts" 
batch actions on the search results. 

• CiviCRM stores first names and last names in separate fields, so these should appear as 
separate columns in your CSV file. The same goes for city and postal code / zip 

code. There are tools built into most common spreadsheet programs that automate the 
process of splitting text across fields. 

• Ensure that your country names are expressed in the same way as they are in CiviCRM, 
i.e. 'United States', not 'United States of America', and 'United Kingdom', not 'England'. 

• If you are importing multiple locations, the first location will be set as the primary 
location address. You may want to move your columns around to ensure the desired 
Location becomes the Primary. You may also need to split your import so that some 
records have one type of record as their Primary, while others have a different one. 
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• If you are importing data into multi-choice (e.g. checkbox or radio) custom fields, your 
data source can use either the label (what's visible to the user in the CiviCRM front end) 
or the value (what's actually stored in the database for that choice) and CiviCRM will 
recognize it and import it appropriately. When importing into multi-choice core data 
fields, you can only use the value in your data source, not the label. 

• If you are updating multiple choice options, new values will replace the entire field, not 
just add values that aren't there. For example, if you update the value of the Colors 
field to be "orange" for a contact that currently has Colors set to "blue", the result will 
be that Colors is set to orange, not orange and blue. 

• Make sure your data source uses an accepted date format and that you select that 
date format on the Choose Data Source screen of the import wizard. 

• Make sure any name prefixes and suffixes you use have been set up in the 
administration interface (Administer -> Option Lists in the navigation menu). 

RUNNING AN IMPORT 

The import process has five steps. 

STEP 1: SET UP 

Set up lets you specify some basic details of your import including the source of the data. 
Data can either come from a CSV file, or from an SQL query of a database on your server. 
Also, you need to check the box if the first row of your file contains column headers. 

Import uses the default strict rule to decide whether a contact record is a duplicate (refer to 
the Deduping and Merging chapter if you're not familiar with duplicate matching rules in 
CiviCRM). You can specify what action to take when import encounters a duplicate. 

• Skip the duplicate contact, i.e. leave the original record as it is. 

• Update the original record with the database fields from the import data. Fields that 
are not included in the import data will be left as they are. 

• Fill in the additional contact data only and leave fields which currently have values as 
they are. 

• No Duplicate Checking, i.e. inserts all valid records without comparing them to existing 
contact records for possible duplicates. 

Import mappings are the way in which you tell CiviCRM how the fields of data in your import 
file correspond to the fields in CiviCRM. If you have a pre-existing field mapping, you can load 
it here. 

STEP 2: MATCH THE FIELDS 

If you had column headings in your file, you will see the title of your column headings on the 
left-hand side of the Field Map, the 2nd and 3rd columns are two rows of data from your file 
to be imported, and the 4th row is the Matching CiviCRM Field. The matching CiviCRM fields 
include the standard data that is included in CiviCRM like First Name, Last Name, etc. as well 
as any custom data fields that have been configured for use with contact records on your 
site. You need to match the fields by clicking the drop down list and selecting the appropriate 
data. For example, if the first title of your column heading is First Name then your your 
Matching CiviCRM Field is First Name. 

Select '- do not import -' for any columns in the import file that you don't want to import into 
CiviCRM. 
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Saved Import Mappings 

If you selected a saved import mapping, the field matching will be preloaded in this step. If this 
is the first time you're importing from this data source, it's a good idea to check the box to 
'Save this field mapping' at the bottom of the page before continuing. The saved mapping can 
then be easily reused the next time similar data is imported. It's also a good idea to save the 
field mapping the first time you do an import because if for some reason your import didn't 
work the first time, your saved Field Map is one less thing to create during the import process. 

If you have a saved mapping for a specific set of spreadsheet columns, and your spreadsheet 
layout has changed (e.g. there are additional columns in the spreadsheet), you can load and 
modify the mapping and resave it. Add your new columns to the end (right side) of the 
spreadsheet to facilitate this process. You can also use a saved field map, change it a bit, and 
then save as a new field mapping. 

STEP 3: PREVIEW 



This screen previews the results of importing your data. It will confirm the number of rows to 
be imported, and allows you to double check that your field matching choices. At the bottom 
of the form, you can choose to add the contacts to an existing group, import to a new group, 
create a new tag or tag imported records. Adding imported records to a separate group is 
strongly recommended in order to be able to quickly find the imports and if necessary delete 
and reimport them. 

If some of the rows in your spreadsheet contain data that doesn't match CiviCRM's 
requirements for one or more fields, you'll see an error message with a count of the "invalid 
rows". At this point it's a good idea to click the Download Errors link and review the errors 
reported in the downloaded file. 
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The final screen reports on the successful imports, and provides you with reports for Duplicate 
Contacts and Errors. If you have set the import to add all contacts to a Group or Tag, you 
can click through to see your imported contact records. 
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16. 



DEDUPING AND MERGING 



Duplicate contacts can turn up in your data for many reasons: mistakes by users who don't 
realize they're creating a contact for someone who is already in CiviCRM; duplicates that aren't 
caught in the import process; and duplicate records created when people fill in forms about 
themselves on your site, amongst others. 

CiviCRM is equipped with duplicate matching rules that can be configured to suit your needs 
and are automatically referenced when creating new records to minimize the chance of 
duplicates, but there are still times when human intelligence needs to be applied to decide 
whether two entries are truly duplicates. CiviCRM also provides a set of tools for finding and 
merging duplicate contacts that do make it into the system. 

DISCOVERING DUPLICATES WITH RULES 

CiviCRM includes two categories of dedupe rules, strict and fuzzy. Different rules are 
configured for each contact type (individuals, organizations, and households.) A default fuzzy 
rule and a default strict rule is set for each contact type. You can view, manage, and use rules 
to find duplicates by going to Administer -> Manage -> Find and Merge Duplicate Contacts 
in the navigation menu. 

Strict rules are configured with a relatively tight definition of what constitutes a match 
because strict rules are used to scan for duplicates without user intervention when importing 
contacts. It is therefore more important that strict rules be structured to avoid false matches 
than that they be able to catch every possible duplicate, as it is easier to sort out duplicates 
later than it is to disentangle two incorrectly merged contacts. An example of a strict rule for 
individuals is that two contacts have identical email addresses, first names, and last names. 

Default strict rules are automatically checked when new contacts new contacts are created 
through online registrations including events, membership, contributions, and profile pages. 
Default strict rules are also used when you import contacts. 

Fuzzy rules are configured with a looser definition of what constitutes a match because they 
are used in instances where human intelligence can be applied to decide whether a match is 
accurate or not; therefore, a wider range of possible match results is both permissible and 
useful. 

Default fuzzy rules are automatically used to check for possible duplicates when contacts are 
added or edited via the CiviCRM user interface. You'll probably also want to use a fuzzy rule 
when scanning your database for possible duplicates. 

CONFIGURING RULES 

To determine whether two contacts are duplicates, CiviCRM checks up to five fields that you 
can specify when creating a new rule or editing an existing rule. You can also set a length 
value which determines how many characters in the field should be compared. For example, if 
you set a length of 2 on the 'First name' field, then 'Mike' would match 'Michael', because the 
first 2 characters are the same. However, if you set the length to 3 instead, "Mike" would no 
longer match "Michael." If the length value is left blank, then the comparison is done on the 
entire field value. 

Each field is also configured with a numeric weight that determines the relative importance of 
a match on that field. When a match is discovered on a field, that field's weight is added to 
the total weight for the rule. If after each field is checked the total weight is equal to or 
greater than the numerical threshold set for the rule, the contacts being compared will be 
listed as suspected duplicates when the rule is used. 
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USING RULES AND MERGING DUPLICATE CONTACTS 

Click Use Rule to scan for duplicate contacts using the selected rule. You can then select to 
search all contacts for duplicates or to search only a particular group. Contacts of the contact 
type to which the rule is assigned will be scanned and compared by CiviCRM. If the match 
between two contacts exceeds the rule's threshold, the contacts will be displayed on the 
following screen of possible duplicates. 

Clicking Merge for any pair of contacts brings up a table showing details for each contact. 
CiviCRM designates one record as the duplicate record and displays its information in the left 
column; the record in the right column is considered the original record into which selected 
data from the duplicate record will be merged. If you want to move the information in the 
opposite direction, there is an option to "Flip between original and duplicate contacts" which 
will swap the duplicate and original designations between the contacts. 

For each field you can choose whether to keep the original data shown on the right or copy 
the duplicate data. Note that associated tags, groups and activity data (including event 
attendance, contributions, etc.) will appear in addition to data already recorded in the original 
record, not in place of it. 
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EXPORTING YOUR CONTACTS 



Exporting is a way of sharing your data with external applications by providing a copy of data 
from CiviCRM in a standard format (CSV - comma separated value) that can be viewed and 
edited in spreadsheet applications, imported into other database applications, or used to 
merge with word processing applications. You can either export a predefined set of fields or 
create your own custom export mapping which can be saved for reuse. 

The export process has three steps. 

STEP 1: SEARCH FOR CONTACTS 

To export contacts, first carry out a search based on your desired criteria using one of the 
available search tools (Quick Search, Find Contacts, Advanced Search, Search Builder, or a 
custom search). 

STEP 2: SELECT CONTACTS YOU WISH TO EXPORT 



Then select all records or choose individual records for export using the checkboxes to the left 
of each record. From the - actions - dropdown, choose Export Contacts and hit Go. This takes 
you to an export wizard. 
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STEP 3: EXPORT ALL OR SELECTED FIELDS 

Choose between exporting the primary fields or selecting your own set of fields for export. 
The primary field export includes all core contact fields (with email, phone, and address data 
as well). If you want to export custom data, you'll want to choose Select fields for export and 
see step 4. 
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STEP 4: SELECT FIELDS TO EXPORT 



If you would like to include specific fields or custom fields, choose this option to select the 
fields you want to export. After selecting your fields you will be given the option of saving the 
export mapping, which enables you to reuse the field set at a later time. 
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TIP: By default, export uses primary location data. If you wish to export non-primary 
addresses you need to explicitly specify the address type. 

If you plan on exporting the same set of fields in the future, click Save this field mapping at 
the bottom of the form, and enter a descriptive name for this type of export. Then click 
Export. 

CiviCRM's export functionality is available to you in any of the search tools and when viewing 
contacts in a group. This also includes component-based search results, where the resulting 
records reflect the component specific data rather than simply core contact data. For 
example, you could export your donors and their contact information for use in a thank you 
letter in which the total amount donated is included from Contributions -> Find 
Contributions. 

By default, a comma is used as the field separator for import and export functions. However 
for some locales, other characters are used (e.g. semi-colon). You can change the separator 
value by navigating to Administer -> Configure -> Global Settings -> Localization and 

modifying the Import/Export Field Separator. 
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POSTAL MAIL COMMUNICATIONS 



It's often thought that in the 21st century there is no longer a need for old-fashioned "snail" 
mail. But you can't send a printed annual report over the internet, and if your constituents 
aren't online - or don't want to be - then postal mail is still an effective and crucial 
communication tool. 

This chapter discusses the different ways that CiviCRM helps with postal mail and post mail 
campaigns. You should have a strong understanding of CiviCRM's search features as well as 
custom fields, activities, profiles, and how to perform mail merges using word processing 
software. 

PLANNING YOUR MAILING 

Before beginning any communication program, take the time to identify goals and plan the 
steps. For our purposes, there are a few key questions to ask before sending out postal 
mailings. 

• What types of mailing do you send out to your constituents? Are mailings always sent to 
everyone in the database or are they frequently targeted to a select list of records? 

• How do you want to greet recipients (e.g. "Dear Jane", "Dear Jane Doe")? 

You have 3 different tools in CiviCRM to generate postal Mailing: 

1. generate labels: useful to quickly print out standard address labels when you don't need 
to personalize their content, for instance to send a printed brochure. 

2. export the contacts and do a mail merge to an external tool (eg. OpenOffice writer or 
Microsoft Word). Refer to the chapter on exporting contacts in the getting around 
section. 

3. Generate PDF Letters and do the merge directly in CiviCRM. 

TIP: Many nonprofit organizations in the United States need to sort recipients of a mailing 
based on zip code for bulk mailing purposes. If this is true for your organization, it is 
recommended you do not create your mailing labels within CiviCRM and instead create them 
using a word processor where you can control the sort order. You can reuse the same 
spreadsheet for your mail merge. 

Fundraising Mailings 

Beside generalized mailings, many nonprofits have specific types of mailings such as thank you 
letters, renewal letters, and general fundraising appeals. The following tips and notes provide 
suggestions for how to handle those types of mailings. 

• Thank-You Letters. Many organizations like to send personalized thank you letters to 
donors thanking them for their support. When doing so, it is often convenient to include 
a specific acknowledgement of the donor's contribution amount. For example, a letter 
would say, "Thank you Judy for your recent contribution of $35." In order to accomplish 
this you will need to create your list using CiviContribute because the results of a search 
using Find Contributions include amounts details. The results also include contact 
information so it can be easily used for mail merge purposes. You can also create a 
custom token to get the latest contribution (cf. custom token chapter) and use the PDF 
letter action. 

• Similar to thank you letters, renewal letters ask members and/or donors to renew 
their membership or previous donation level. In the case of renewals, it may be more 
useful to use Memberships -> Find Members to retrieve their membership type and 
expiration date. 
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GREETINGS AND SALUTATIONS 

An important part of a postal mailing is including a salutation that is personable and friendly. 
Many people also prefer to be greeted in a special way if they are a doctor or esteemed 
person like a politician. 

You can set a specific postal greeting format for each contact. There are several options from 
more friendly "Dear John", to more formal "Dear Mr. John Doe". You can also enter a 
customized greeting ("Your royal highness"). Postal greetings can be edited in the 
Communications Preferences section of the contact edit form. If you need to set or reset 
postal greetings en mass, refer to the Command Line Script Configuration documentation: 

http://wiki.civicrm.Org/confluence/x/LIK9AQ 

PRINT PDF LETTER 

The workflow is as usual to select the group you want to target, then choose the action "Print 
PDF letter". These letters will then be outputted as a PDF, allowing you to easily print them. 
To create the letter: 

1. Search for your contacts, click on Search -> Find Contacts or Find Contacts - Advanced 
Search. 

2. Enter your search criteria and click Search. 

3. Select the records that you wish to write a letter to. 

4. Click " - actions - ," choose "Print PDF Letter for Contacts" and click Go. 

5. Create your letter, using the formatting options provided. You can also personalize the 
letter by using tokens. Postal Greeting is a commonly used token for this purpose. Click 
in the body of the letter where you want to enter the token. Then click on "Insert 
Tokens," located above the letter at the top right and select the desired token. 

6. Before you move to the next screen, you should decide whether the format of this 
letter could be used again. If so, check the "Save New Template" box and enter the 
Template Title. 

7. When your letter is finished scroll to the bottom and click "Make PDF Letters." 

8. You will get a popup on your computer that offers the option of opening or saving the 
PDF. Open and review your letter and then print them. Or save your PDF and review at 
your leisure. 



{comacl.poslal_greetlng}| 






Select Token 


X 










pos 




Begin typing to filter list of tokens 




Postal Code 
Postal Code Suffix 


Postal Greeting 








Done 



TIP: You can use this feature for any kind of document, not only letters. You might want to 
use it to print attendance certificates for a workshop for example. 

GENERATE MAILING LABELS 
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For mailing labels, perform the search to select the contacts you want to target and choose 
Mailing Labels from the '- actions -' dropdown. Then select the mailing label style, determine if 
you want to exclude people with "do not mail" checked in their privacy options (checked by 
default and recommended), and whether you want to merge two records in your search result 
with the same mailing address into one label. 

This last option is very useful when sending a mailing to a households or organizations where 
you don't want them to receive duplicate mailings. When the records are merged, each name 
at that address is listed on a separate line on the label. 

Your system administrator can configure the fields included in mailing labels. Read the chapter 
Address Settings to learn more about the options. 
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ESSENTIAL TASKS 



This chapter provides instructions on how to do some of the common tasks associated with 
the CiviEngage module. 

PRINTING A WALK LIST 

CiviEngage offers a report that allows you to easily print walk lists for folks who are doing 
canvassing, Get Out the Vote (GOTV) or other door knocking activities. 

1. If you want to use Groups or Smart Groups to develop your walk list, be sure to create 
the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the walk list report. Choose whether you want the Country or Email field to 
display. 

4. Scroll down to the "Set Filters" section. You must select a filter to obtain results. All 
your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the report results, but if you click on "Print Preview" you will see your walk list. 
You can use your browser's Print Preview feature to see the walk list on a per-page 
basis. 

PRINTING A PHONE LIST 

CiviEngage offers a report that allows you to easily print phone lists for folks who are doing 
phone banks or other mass phoning activities. 

1. If you want to use Groups or Smart Groups to develop your phone list, be sure to 
create the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the phone list report. Choose the columns you want to display from the 
template screen. 

4. Scroll down to the "Set Filters" section. You must select a filter in order to obtain 
results. All your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the results but if you click on "Print Preview" you will see your phone list. You can 
now use your browser's Print Preview feature to see the phone list on a per-page basis. 

CREATE A CAMPAIGN SOURCE CODE 

In order to use CiviEngage effectively, you need to create "campaigns" that you connect all 
your activities to. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Participant Info in the list and click the corresponding "View and Edit Custom Fields" 
link. This gives you a list of Custom Fields. 

3. Find Participant Campaign Code and click the "Edit Multiple Choice Options" link. Now you 
are seeing a list of the interests. 

4. Scroll down and click on "New Option" and add your new campaign. 

Please note that this new campaign code will now be available for Event, Membership and 
Contribution Campaign Codes as well as in the Participant Campaign Code that it was just 
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created in. 

ADD AN ISSUE INTEREST 

To better understand and track the areas that your members and constituencies are 
interested in working on, CiviEngage provides a field that collects this information. Customize 
this list to meet the needs of your particular organization. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Grassroots Info in the list and click on the corresponding "View and Edit Custom 
Fields" link. This gives you a list of Custom Fields. 

3. Find Issue Interest and click the "Edit Multiple Choice Options" link. Now you are seeing a 
list of the interests. 

4. Scroll down and click "New Option" and add your new interest. 

Please note that this new issue will also appear in Funding Areas and Funder Issue Interest as 
well as in the Issue Interest that it was just created in. 

TRACK WALK LIST/CALL LIST RESPONSES 

Responses to the questions your canvassers or phone bankers ask are tracked in an 
individual's activity record. The text of the questions are tracked in the event record. In order 
to properly configure this, start with creating the event. 

1. Click on Events -> New Event. 

2. Choose Campaign for your Event Type, which will let you see the Event Campaign Details 
section. 

3. Scroll down to the Event Campaign Details section and add the text to the questions for 
this particular campaign. 

4. You will also want to add an Event Campaign Code, which is in the Event Details section. 

Next you would go to a contact record to create a "Door Knock" or "Phone Call" activity and 
finish configuring this functionality. 

1. Go to a contact's record and click on "new activity." 

2. Choose "Phone Call" or "Door Knock" and you will get the Activities screen. 

3. Scroll down and click on the Call List Responses section. 

4. Now you can record the responses. 

5. You then add the Activity Campaign Code in the Activity Source Details section. Make 
sure you choose the same campaign as you did for the Event. 
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PRINT AN ACTIVITY REPORT 

One of the features of CiviEngage is the ability to track the different activities that your 
members are engaged in. Use the activity report to better understand what your members 
are doing. 



100 



1. Click on Reports -> Create Reports from Template . 

2. Choose the Activity Report. This brings up the Activity Report Template. You are now 
looking at all the options available for printing a report based on the activities CiviEngage 
offers that your contacts are engaged in. 

3. The first section lists the columns that are available for your report. Use the check 
boxes to decide what information you want your report to show. The default values are 
Assignee Contact Name , Target Contact Name , Activity Type , Subject, Activity Date and 
Activity Status . You can choose columns from Walk List Responses, Leadership Level 
(from Activities), Call List Responses, Proposal Info or Activity Source Details. 

If, for example, you want a report of Walk List Responses from a specific campaign, you 
would check boxes from the Walk List Responses section and choose the Activity 
Campaign Code from the Activity Source Details section. Please note that the default 
value for Activity Date is "this month." If you want a different range of dates you have 
many options. Click on "this month" and you will see all the options available. Included is 
Date Range, where you can choose a specific range of dates. 

4. The next section allows you to group your data by the Source Contact (the default 
value), Activity Date or Activity Type . Check the appropriate box for your report. 

5. The final section is for filtering your data. Here you can choose data from any of the 
activity fields that CiviEngage offers. 

To continue our example, you might choose to include data where the first two Walk 
List questions were answered yes. Choose Y in the appropriate boxes and scroll down to 
the Activity Source Detail section and choose the appropriate Activity Campaign Code . 
Click Preview Report and view your results. 

6. Once you have your results, you have a number of options. You can "Preview" the 
report, "Preview" the PDF of the report, "Preview" the CSV (export your report into a 
spreadsheet), or "Add the contacts to a group." 

SEARCH FOR ACTIVITIES 

The are a number of ways to search for the activities that you create using CiviEngage: 

• Run a report, as explained above 

• Use the Find Activities search option 

• Use the CiviCRM Advanced Search 

• Run an Activity Search, which is in Custom Searches. 

Using the Find Activities search option 

1. Click on Search -> Find Activities . 

2. You are presented with a number of search criteria options. You can enter the name or 
email address of a contact in the database. You can choose one or more activity types. 
You can add a range of dates during which activities happened. You can search for 
contacts in specific Activity Roles: With, Created By and Assigned to. You can look for 
specific subjects, test activities or by the status of the activity. Each criterion you select 
will narrow your search results. 

3. Click Search and you will get to the Search Results screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using Advanced Search to find Activities 
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1. Click on Search -> Find Contacts - Advanced Search . 

2. Scroll down to the Activities section and click on it. Here you find all the options available 
in CiviEngage for activities. 

3. Once you choose your search options and click Search you will get to the Search Results 
screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using the Custom Search: Activity Search 

1. Click on Search -> Custom Searches... -> Activity Search . 

2. You are presented with different criteria by which you can search for information. Enter 
your search terms and click Search. 

3. The Search Results provides the Name of the person, the Status, Type and Subject of 
the Activity and who assigned the activity. You also have a button for viewing and 
editing each activity record. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 
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20. 



WHAT IS CIVICONTRIBUTE? 



This chapter gives a brief outline of CiviContribute and the roles it plays in CiviCRM. 

CiviContribute serves two main purposes in CiviCRM. It provides a framework to help your 
organisation raise money through fundraising campaigns and donations, and it provides a 
framework that other CiviCRM components can plug in to for activities that have financial 
elements, for example paid event fees and membership fees. 

CiviContribute comes with a number of out of the box tools for raising money through your 
website, including contribution pages which can be set with fundraising targets, personal 
campaign pages and tell a friend functionality so you can get your supporters engaged in 
raising money for your organisation and give them credit for any money that raise from other 
people on your behalf. Campaigns also have a thermometer style widget that you embed on 
websites and blogs, etc. 
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PLANNING WITH CIVIENGAGE 

CiviEngage packages a set of custom data groups and fields, reports, and other features for 
use in civic engagement and community organizing work. This chapter will describe the general 
concepts and planning needed to use CiviEngage effectively. 

WHAT YOU NEED TO KNOW 

The following are concepts, custom fields and values to keep in mind when preparing to use 
CiviEngage. 

Campaign Source Code 

Campaign Source Codes are descriptive values used to identify related activities, events, 
contributions, and memberships and map how these activities and transactions are linked 
together. Campaign Source Codes are also useful for identifying these sets of activities or 
transactions as part of a larger campaign, project, or program. 

For example, an organization is conducting a door knock canvass around a particular issue 
during a specific range of dates. The organization may want to use campaign source codes to 
link together the activities (where responses to door knock canvass questions are captured), 
the event (the door knock canvass campaign itself), and any contributions made during the 
canvass to be able to analyze the effectiveness of the campaign. 

Activity, Event, Contribution, Participant, and Membership records each contain a custom field 
to store a Campaign Source Code, that all share a common option list where Campaign Source 
Code values can be added and edited. 

Your organization can establish a standard method for creating new Campaign Source Codes 
so that the codes are consistent and easy to sort and understand at a glance. For example, 
you can specify that annual campaigns always include the year at the either the beginning or 
the end of the Campaign Source Code, not both, so that you don't wind up with "2009 Annual 
Campaign" and "Annual Campaign 2010." 

Issue Interests 

Issue Interests are issues that your organization works on or tracks. They are included in 
CiviEngage as a single option list shared across multiple contexts: 

• Grassroots Info: Issue Interests for individuals 

• Media Issue Interests for media contacts 

• Funder Issue Interests for funders 

• Grant Info: Funding Areas for organizations 

It is important to remember that despite appearing with different labels in these different 
contexts, you are still dealing with just one shared list of options. 

In planning to use CiviEngage you should come up with a list of distinct issues that are 
important to your organization and that you will want to utilize when tracking individuals' 
interest in your organization's work, the issues that your media contacts may be interested in 
covering, funders' general interests and the specific areas of work included in particular grants. 

Volunteer Interest 
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Volunteer interests are activities that your organization's volunteers can take on and 
participate in; you can indicate each individual's interest in participating in these ways. They 
are included in CiviEngage as an option list. In planning to use CiviEngage you should establish a 
list of your organization's current volunteer activities as well as any activities that you are 
planning to launch in the future. Some examples of volunteer interests are canvassing, phone 
banking, and tabling. 

Cleaning your Address Data 

Cleaning your address data means standardizing addresses to conform to the conventions 
defined by the United States Postal Service's Standards for Addresses. Standardizing how 
addresses are entered into CiviCRM will allow for more accurate search results when searching 
by address and is essential to generate accurate Walk List reports. CiviCRM will parse 
addresses based on the USPS standards. To find out more about how Address Parsing is 
handled and used in CiviCRM, refer to the Address Parsing chapter of this book. When adding 
or editing contacts you will be entering or editing address elements including street number, 
street name, and Apt/Unit/Suite number according to these standards. 

When planning to import pre-existing data into CiviCRM for use in CiviEngage it is essential that 
you plan to clean up address data before importing. 

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 
at http://pe.usps.com/text/pub28/welcome.htm . 

TRACKING CIVIC ENGAGEMENT AND CAMPAIGNS 

CiviEngage is designed to manage interactions with constituents around an organization's civic 
engagement and base-building work, such as door knock canvassing and phone banking. There 
are several concepts and details to consider when preparing for these types of campaigns. 

Working with Your Universe of Contacts 

In preparing for your campaign, you will need to identify the audiences you will be targeting for 
your door knock canvass or phone bank in CiviCRM. CiviCRM uses Smart Groups and regular 
Groups as the mechanisms to target specific groups of contacts. Here are a couple of 
examples of how you can use Smart Groups and regular Groups for targeting during your 
campaign: 

• You can use Smart Groups to identify contacts you want to target based on specific 
criteria, such as voter demographics, issue interests, primary language spoken, etc. 

• You can track voter demographics about your contacts using the custom data group 
called Voter Info 

• You can use Groups to identify contacts who subscribe to a particular newsletter or 
issue to do an email blast about your campaign. 

• You can then use these Smart Groups and regular Groups to generate your walk list or 
phone bank list. 

Learn more about working with Smart Groups and regular Groups in the "Tags and Groups" 
chapter of this book. 

Preparing a Campaign Event 

To prepare a campaign event in CiviCRM, there are several setup items you may want to 
consider: 
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• Define a specific Campaign Source Code for your event. This Campaign Source Code will 
be used for the event and the activity which holds the individual responses gathered 
during the door knock canvass or phone bank campaign. 

• When you set up your event with the Event Type set to "Campaign" you can record 
the questions being asked during the campaign in the Event Campaign Details area. 

• Decide how you want to identify participants in the campaign event. Maybe you only 
want to identify the staff and volunteers who will be involved in conducting the door 
knock canvass or phone bank. Maybe you'll want to add the targeted contacts as 
participants. Activities will be used to record the responses of each individual contacted 
during the campaign as well as the campaign source code related to the campaign, so it 
may not be necessary to add these contacts to the event. In either case, it is 
recommended to also record the Campaign Source Code in the participant's record in 
the Participant Info area. 

• When capturing responses from each individual during the campaign, consider how you 
plan on getting the data back into CiviCRM. If the plan is to enter data one contact at a 
time, which may make sense for phone banking, you will need to record the response in 
the individual's activity record, with the Activity Type of "Door Knock" or "Phone" in 
the Walk List Responses or Call List Responses area. But if you plan on entering 
batches of data at a time, then you will need to plan to import the responses using the 
Import Activities function. 

Working with Voter History 

When using CiviEngage, plan how you will manage voter history and other voter information 
collected during a voter engagement or electoral cycle. Many organizations have access to a 
voter file from which they manage all their voter engagement work outside of CiviCRM. Once 
the voter engagement or electoral campaign is over and voter information is updated with 
who voted and other demographics, organizations most often will only want to keep 
information on the actual contacts they made during the campaign. In this case, only those 
selected records from the voter file and additional voter information, such as responses to 
specific electoral campaign questions, will be imported and maintained in CiviCRM. These voter 
records then become contacts that organizers will continue to engage and target with base- 
building efforts. 

If you wish to collect voter contacts with their demographics, history, and additional 
information, first import voter contacts (with their contact information and demographics) into 
the Voter Info custom group. Then import additional information as Activities, such as 
responses to electoral campaign canvass questions. 

MOBILIZING INDIVIDUALS TO ATTEND AN EVENT 

The Participant Info custom data group that comes with CiviEngage contains fields that hold 
information about prospective event participants, including a history of interactions between 
your organization and prospective participants. Use this information (such as needs for 
childcare or rides) to bring these individuals to your events. Tracking the history of your 
organization's contact with individuals around events such as an annual membership meeting, 
a direct action, or leadership training can help you to understand the effectiveness of your 
outreach methods and determine how committed or engaged an individual is based on if the 
individual actually attends events after multiple contacts. 

This feature is mostly useful for organizers or staff who have a list of individuals they are 
recruiting to attend an event through multiple phone calls or face-to-face meetings. The 
following CiviCRM tasks could be used to mobilize individuals: 
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1. Conduct a basic or advanced search or use Groups and Smart Groups to create a list of 
the contacts you want to mobilize or invite to the event. 

2. From the search results or Group Contacts screen, you can add the list of contacts to 
the event by selecting Add Contacts to Events from the Actions list. To find out more 
about how to add contacts to events, refer to the Managing Participants chapter in the 
Events section in this book. 

3. Once you add the contacts to the event, you can enter participant information or 
responses from multiple interactions in the Participant Info area in a contact's 
participant record. You can either enter information for one participant by editing the 
participant record itself, or you can add information for a list of participants at one time. 
For example, if you plan to call through your list by viewing the participant list from the 
event listing, you could use Batch Update Participants Via Profile and select one of 
the following custom profiles provided by CiviEngage: 

• Update Event Invite Responses - to record responses from multiple contacts with the 
participant. 

• Update Participant Info - to record general information about participants, such as if 
they need childcare or rides to the event. 

TRACKING FUNDERS AND FOUNDATIONS 

You can track information about and due dates for grant proposals, letters of inquiries, and 
reports for funders by adding an activity related to the funder's contact record and choosing 
from the Proposal, Letter of Inquiry, or Report activity types. 

You can also tailor information about an individual funder, such as their funding areas and 
issue interests, using the Funder Info custom group. In order to view the Funder Info tab, you 
will need to use the Individual sub-contact type, Funder, when you create a new contact that 
is identified as a funder. 

You can tailor information about a foundation (organization record), such as their program 
areas for funding, using the Grant Info custom group. 

TRACKING MEDIA CONTACTS 

As part of civic engagement and community organizing work, it can be useful to track 
information about your media contacts in CiviCRM, especially if you want to know which media 
contacts or outlets are interested in your organization's issues, or have written articles about 
your work, or for identifying who to contact when you want to publicize the work the 
organization is undertaking. 

You can tailor information about an individual media contact, such as their media type (e.g., 
TV, Newspaper, Photographer, etc.), issue interests and beat using the Media Info - Ind 
custom group. Use the Individual sub-contact type, Media Contact, when you create a new 
contact for a media contact. You can then view and edit the Media Info - Ind tab. 

You can also tailor information about a media outlet (organization) such as their media type 
(e.g., TV, Newspaper, Magazine, etc.) using the Media Info - Org custom group. As with the 
individual media person, use the Organization sub-contact type, Media Outlet, when you 
create a new contact for a media outlet. You can then view and edit the Media Info - Org 
tab. 

TRACKING ELECTED OFFICIALS 

Identifying and collecting information about your elected officials could be useful for your 
community organizing and civic engagement work. You may want to know who is an elected 
official in a specific district, or who to contact on their staff, such as the scheduler, or 
spokesperson. 
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You can tailor information about an individual elected official, such as their elected position 
(e.g., city council, Senate, etc.) and their role using the Elected Info custom group. Use the 
Individual sub-contact type, Elected Official, when you create a new contact for an elected 
official. You can then view and edit the Elected Info tab. Remember that staffers, schedulers, 
or spokespeople for an elected official can be entered as the Elected Official subtype. 

REPORTING AND ANALYSIS 

There are two reports packaged with CiviEngage: Walk List and Phonebank List. In addition, 
the Activity Report is enhanced to filter custom activity fields such as those associated with 
the custom group Call List Responses and Walk List Responses. 

The Walk List report allows you to view, print, or export an individual's contact information 
and demographics such as Member Type, Sex, Age, Party Registration, Voter history, along 
with response codes and notes where a volunteer can collect responses during a door knock 
canvass. 

The Phonebank List report is similar to the Walk List report except that this report is used 
exclusively during a phonebank and contain response codes pertaining to phone responses. 

The Walk List and Phonebank List reports are used to collect information during a campaign to 
later be imported or batch entered back into CiviCRM. 

The Activity Report is enhanced to allow you to search, view, print, or export for specific 
responses from a door knock canvass or phonebank campaign. Use this report not only to 
analyze the effectiveness of your campaign (e.g., how many people you contacted and 
collected responses from) but also to analyze responses from your constituency around an 
issue, or to determine whether individuals may become more involved with your 
organization. 

Disabling vs. Deleting Custom Data 

If you decide you don't need to use or view particular custom groups, fields, or values, we 
strongly recommend that you disable the group, field, or value rather than delete them. The 
Walk List and Phonebank List reports rely on these fields, so deleting certain custom data 
could potentially "break" the reports. 
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CONFIGURATION 



You will need to configure both Drupal and CiviEngage to use the module. 

CONFIGURING CIVICRM FOR CIVIENGAGE 

CiviEngage can be configured using the following CiviCRM core features: 
Custom Data Groups 

Configure custom data groups and fields to track voter demographics, issue interests, 
leadership levels, volunteer interests, and information about funders, media contacts, and 
elected officials. 

Contact Subtypes 

CiviEngage takes advantage of CiviCRM contact subtypes to expose custom data groups 
associated only with specific subtypes. The following are new contact subtypes: 

Individual subtypes: 

• Media Contact - will expose a contact tab containing information specific to media 
contacts, such as their media type (e.g. Newspaper, Radio, TV, etc.), their "Beat," and 
the media issue interests 

• Elected Official - will expose a contact tab containing information specific to elected 
officials, such as their elected level (e.g. City Council, Senate, etc.) and the role (e.g. 
scheduler, spokesperson, etc.) 

• Funder - will expose a contact tab containing information specific to funders, such as 
their program areas and their issue interests. 

Organization subtypes: 

• Media Outlet - will expose a contact tab containing information about their type of 
media, such as TV, Radio, Wire, Newspaper, Magazine, etc. 

Campaign Source Codes 

CiviEngage uses Campaign Source Codes that you can tailor to describe and track related 
activities, events, event participants, contributions, or memberships. Campaign Source Codes 
can be used to describe a group of related activities, events, contributions, or memberships 
for a specific campaign, project, or program. 

Note: A "Campaign" does not necessarily mean a formal campaign, but can also generally be 
defined as a specific project, program, or organizing activity. 

Door Knock Canvass and Phone Bank Tracking 

• Events used for Door Knock Canvass or Phone Bank - Use the Campaign Event Type to 
expose Event custom fields that allows you to store up to four specific questions being 
asked during a door knock canvass or phone bank. 
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Activities used to Collect Responses from Door Knock Canvass or Phone Bank 
Campaigns - Use the Door Knock and Phone Call Activity Types to expose custom 
fields where you can collect an individual's responses during a door knock canvass or 
phone bank. 



Reports 

• Walk List Report - view, print or export certain demographic and other constituent 
information in a specific geographic area to collect responses to be used during a door 
knock canvass. The Walk List Report takes advantage of the optional address parsing 
feature to build the report. 

• Call List Report - view, print or export certain demographic and other constituent 
information along with an area to collect responses to be used during a phone bank. 

• Activity Report - includes filters for activity custom fields so that you can build a report 
of specific activities based on criteria about your constituency, such as creating a report 
to analyze particular responses from a door knock canvass or phone bank. 

Grant Proposal and Report Tracking 

CiviEngage uses the Proposal, Letter of Inquiry and Report Activity Types to expose custom 
fields to track information and schedules for proposals, letters of inquiries and reports related 
to an individual funder or foundation. 

Custom Profiles 

CiviEngage configures several custom profiles for easier batch updating of individual or 
organization information, such as voter demographics, issue interests, volunteer interests, or 
event participant information. To learn more about profiles, please refer to the "Profiles" 
section of the book. 

CONFIGURING CIVIENGAGE 

When you install CiviEngage a number of custom fields are automatically created. These fields 
are designed to support your community organizing work. Most of these fields are multiple 
choice fields which have been pre-populated with sample options. Before you start using 
CiviEngage, you need to review and modify the supplied options to meet your needs. 

Begin by going to Administer -> Customize -> Custom Data in the navigation menu. In the 
following list bolded items are Group Header entries in the Custom Data screen. The bulleted 
items are custom fields under those Group Headers that have been added by CiviEngage; the 
other fields under these group headers are standard to CiviCRM. The choices for these custom 
fields should be edited before you use CiviEngage. You should add, delete, or edit the available 
options for each custom field to make them better fit your organization's needs. 

Communications Details 

• Best Time to Contact 
Voter Info 

All of the fields in this custom data group are added by CiviEngage, so you should review and 
edit them all to suit your needs. You may also want to add specific local voter fields that apply 
to you. 

Constituent Info - Individuals 
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• Constituent Type 

• Staff Responsible - note that the values for this field are also used for Event Contact 
Person. Replace the sample names in the list with your staff, member or volunteer 
coordinators, and other folks that have individuals assigned to them. 

• How Started - edit this list to fit the ways in which members are brought into your 
organization. 

Grassroots Info 

• Member Status - three status choices included by default. Think about other member 
statuses that might work for your organization and add or remove as needed. 

• Leadership Level - The default options for tracking an individual's leadership level within 
your organization are 1-5. Change this to match however your organization tracks this 
information. 

• Issue Interest - this custom field uses the same set of options as the Funding Areas and 
Funder Issue Interest fields. It is a list of issues that your organization works on or 
tracks. 

• Volunteer Interests - a list of volunteer activities that your members can take on. 



Constituent Info - Organizations 

• Constituent Type - Org 
Grant Info 

• Funding Areas - this custom field uses the same set of options for Issue Interest and 
Funder Issue Interest. 

Participant Info 

• Participant Campaign Code - this custom field uses the same set of options as the 
Contribution Campaign Code, Event Campaign Code, Activity Campaign Code and 
Membership Source Code fields. Delete the example campaigns and add your own. This 
is the mechanism CiviEngage uses to connect a contact's participation across all these 
different actions. For example, a Campaign called "House Party 10-1-2010" could have an 
Event tied to it, a participant of that Event tied to it, an activity when an organizer calls 
a contact inviting them to attend an Event, a membership entry when they become 
members at the Event and a contribution when they pay their dues. 

Contribution Source 

• Contribution Campaign Code - see Participant Campaign Code. 

• Contribution Campaign Method - this custom field uses the same set of options as 
Membership Source Campaign. Add different types of interactions or locations where 
you would be engaging potential members and donors. 

Event Details 

• Event Contact Person - also used for Staff Responsible. Add all appropriate people to 
this list. 

• Event Campaign Code - see Participant Campaign Code. 

Activity Source Details 

• Activity Campaign Code - see Participant Campaign Code. 

Organizational Details 

This custom group is used to store information that is specific to organizations. There is only 
one example currently. 
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• Rating - if you need to evaluate organizations in some way, change the options to reflect 
that. 

Demographics 

• Ethnicity 

• Primary Language - this custom field uses the same set of options as Secondary 
Language. Only one entry can be selected for each contact for this field. 

• Secondary Language - also used for Primary Language, but as many choices as needed 
can be checked. 

Media Info - Org 

This custom group is only applicable to the New Media Outlet contact subtype. 

• Media Type - Org - this custom field uses the same set of options as Media Type - Ind: 
TV, Radio, Wire, Newspaper, Magazine 

Media Info - Ind 

This custom group is only applicable to the New Media Contact contact subtype. 

• Media Type - Ind - this custom field uses the same set of options as Media Type - Org 

• Beat - this refers to the general category of topics that a media contact covers, such as 
local government, education, neighborhoods, religion, labor, etc. 

• Media Issue Interest - uses the same option list as Issue Interest. As you come to know 
a reporter, you will learn the issues they are particularly interested in, even if it differs 
from their assigned beat. 

Elected Info 

This custom group is only applicable to the New Elected Official contact subtype. 

• Elected Level - the governmental body the individual is part of (City Council, state 
legislature, mayor, etc.) 

• Role - Whether the contact is the elected official, or the official's staff, spokesperson, 
etc. 

Funder Info 

This custom group is only applicable to the New Funder contact subtype. 

• Funder Issue Interest - this custom field uses the same set of options as Issue Interest 
and Funding Areas. 

Membership Source Details 

• Membership Source Code - Uses the same codes as the Participant Campaign Code and 
Contribution Campaign Code. 

• Membership Source Campaign - also used for contributions. Add different types of 
interactions or locations where you would be engaging potential members and donors. 
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ESSENTIAL TASKS 

This chapter provides instructions on how to do some of the common tasks associated with 
the CiviEngage module. 

PRINTING A WALK LIST 

CiviEngage offers a report that allows you to easily print walk lists for folks who are doing 
canvassing, Get Out the Vote (GOTV) or other door knocking activities. 

1. If you want to use Groups or Smart Groups to develop your walk list, be sure to create 
the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the walk list report. Choose whether you want the Country or Email field to 
display. 

4. Scroll down to the "Set Filters" section. You must select a filter to obtain results. All 
your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the report results, but if you click on "Print Preview" you will see your walk list. 
You can use your browser's Print Preview feature to see the walk list on a per-page 
basis. 

PRINTING A PHONE LIST 

CiviEngage offers a report that allows you to easily print phone lists for folks who are doing 
phone banks or other mass phoning activities. 

1. If you want to use Groups or Smart Groups to develop your phone list, be sure to 
create the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the phone list report. Choose the columns you want to display from the 
template screen. 

4. Scroll down to the "Set Filters" section. You must select a filter in order to obtain 
results. All your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the results but if you click on "Print Preview" you will see your phone list. You can 
now use your browser's Print Preview feature to see the phone list on a per-page basis. 

CREATE A CAMPAIGN SOURCE CODE 

In order to use CiviEngage effectively, you need to create "campaigns" that you connect all 
your activities to. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Participant Info in the list and click the corresponding "View and Edit Custom Fields" 
link. This gives you a list of Custom Fields. 

3. Find Participant Campaign Code and click the "Edit Multiple Choice Options" link. Now you 
are seeing a list of the interests. 

4. Scroll down and click on "New Option" and add your new campaign. 

Please note that this new campaign code will now be available for Event, Membership and 
Contribution Campaign Codes as well as in the Participant Campaign Code that it was just 
created in. 

ADD AN ISSUE INTEREST 
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To better understand and track the areas that your members and constituencies are 
interested in working on, CiviEngage provides a field that collects this information. Customize 
this list to meet the needs of your particular organization. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Grassroots Info in the list and click on the corresponding "View and Edit Custom 
Fields" link. This gives you a list of Custom Fields. 

3. Find Issue Interest and click the "Edit Multiple Choice Options" link. Now you are seeing a 
list of the interests. 

4. Scroll down and click "New Option" and add your new interest. 

Please note that this new issue will also appear in Funding Areas and Funder Issue Interest as 
well as in the Issue Interest that it was just created in. 

TRACK WALK LIST/CALL LIST RESPONSES 

Responses to the questions your canvassers or phone bankers ask are tracked in an 
individual's activity record. The text of the questions are tracked in the event record. In order 
to properly configure this, start with creating the event. 

1. Click on Events -> New Event. 

2. Choose Campaign for your Event Type, which will let you see the Event Campaign Details 
section. 

3. Scroll down to the Event Campaign Details section and add the text to the questions for 
this particular campaign. 

4. You will also want to add an Event Campaign Code, which is in the Event Details section. 

Next you would go to a contact record to create a "Door Knock" or "Phone Call" activity and 
finish configuring this functionality. 

1. Go to a contact's record and click on "new activity." 

2. Choose "Phone Call" or "Door Knock" and you will get the Activities screen. 

3. Scroll down and click on the Call List Responses section. 

4. Now you can record the responses. 

5. You then add the Activity Campaign Code in the Activity Source Details section. Make 
sure you choose the same campaign as you did for the Event. 
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PRINT AN ACTIVITY REPORT 

One of the features of CiviEngage is the ability to track the different activities that your 
members are engaged in. Use the activity report to better understand what your members 
are doing. 



1. Click on Reports -> Create Reports from Template . 

2. Choose the Activity Report. This brings up the Activity Report Template. You are now 
looking at all the options available for printing a report based on the activities CiviEngage 
offers that your contacts are engaged in. 

3. The first section lists the columns that are available for your report. Use the check 
boxes to decide what information you want your report to show. The default values are 
Assignee Contact Name , Target Contact Name , Activity Type , Subject, Activity Date and 
Activity Status . You can choose columns from Walk List Responses, Leadership Level 
(from Activities), Call List Responses, Proposal Info or Activity Source Details. 

If, for example, you want a report of Walk List Responses from a specific campaign, you 
would check boxes from the Walk List Responses section and choose the Activity 
Campaign Code from the Activity Source Details section. Please note that the default 
value for Activity Date is "this month." If you want a different range of dates you have 
many options. Click on "this month" and you will see all the options available. Included is 
Date Range, where you can choose a specific range of dates. 

4. The next section allows you to group your data by the Source Contact (the default 
value), Activity Date or Activity Type . Check the appropriate box for your report. 

5. The final section is for filtering your data. Here you can choose data from any of the 
activity fields that CiviEngage offers. 

To continue our example, you might choose to include data where the first two Walk 
List questions were answered yes. Choose Y in the appropriate boxes and scroll down to 
the Activity Source Detail section and choose the appropriate Activity Campaign Code . 
Click Preview Report and view your results. 

6. Once you have your results, you have a number of options. You can "Preview" the 
report, "Preview" the PDF of the report, "Preview" the CSV (export your report into a 
spreadsheet), or "Add the contacts to a group." 

SEARCH FOR ACTIVITIES 

The are a number of ways to search for the activities that you create using CiviEngage: 

• Run a report, as explained above 

• Use the Find Activities search option 

• Use the CiviCRM Advanced Search 

• Run an Activity Search, which is in Custom Searches. 

Using the Find Activities search option 

1. Click on Search -> Find Activities . 

2. You are presented with a number of search criteria options. You can enter the name or 
email address of a contact in the database. You can choose one or more activity types. 
You can add a range of dates during which activities happened. You can search for 
contacts in specific Activity Roles: With, Created By and Assigned to. You can look for 
specific subjects, test activities or by the status of the activity. Each criterion you select 
will narrow your search results. 

3. Click Search and you will get to the Search Results screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using Advanced Search to find Activities 



1. Click on Search -> Find Contacts - Advanced Search . 

2. Scroll down to the Activities section and click on it. Here you find all the options available 
in CiviEngage for activities. 

3. Once you choose your search options and click Search you will get to the Search Results 
screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using the Custom Search: Activity Search 

1. Click on Search -> Custom Searches... -> Activity Search . 

2. You are presented with different criteria by which you can search for information. Enter 
your search terms and click Search. 

3. The Search Results provides the Name of the person, the Status, Type and Subject of 
the Activity and who assigned the activity. You also have a button for viewing and 
editing each activity record. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 
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WHAT IS CIVIEVENT? 



CiviCRM provides powerful and exciting tools for managing events and provides real-time 
registration forms through your website (CiviEvent). By harnessing the power of CiviCRM you 
can centralize your registration data process, provide your constituents the ability to register 
online with credit cards, and even have live access to your data while on site at the event. 

It is integrated with all the other functions of CiviCRM, so you can then send a targeted email 
to the list of participants, or only to the ones that canceled and that have a role of volunteer 
for instance. Moreover, each registration is added to the list of activities of each contact, 
letting you see that Mr Doe registered 15 hours after having received your monthly newsletter. 

SCENARIO 

Organizations have taken advantage of features of CiviEvent to lighten the task load when 
planning and managing events. Here is a scenario of how an organization is using CiviEvent. 

Recruiting for the Annual Youth Leadership Workshop 

A community organizing group holds leadership workshops for youths 25 and younger as their 
major yearly event. They also invite youth speakers and volunteers, as well as several other 
speakers for the training workshops. The organization also charges nominal fees for meals and 
lodging, a flat fee for the registration fee, and additional costs for optional workshops. 
Information about the participants will also be collected about their food and lodging 
preferences. The event invite is usually sent to a targeted audience contact list to ensure 
their core constituency attends, and the event will also be announced more broadly by posting 
it on the website to allow for online registrations. At the end of the event, staff will want to 
evaluate the success of the event and report results of the event, such as number of 
attendees, total event fees paid, and total amount still due. 

To prepare for the event, the organization will plan out their data needs and the tasks needed 
to configure the event as well as keep tabs on the registration and event management 
process. Here are some items that the organization plans to in preparation for the day of the 
event: 

• Organizers will need to build their targeted list of people they want to invite to the 
event 

• A Staff person will need to set up the website to show the event 

• A Staff person will decide and configure the pricings for the different event fees: 
registration fee; cost for the meals; cost for lodging; costs for optional workshops 

• A staff person will configure CiviEvent to collect information about the participant online 
about their food and lodging preferences 

• A staff person will set up an event template and email message template that could be 
used every year in order to ease the process of setting up similar events over time 

• During the event registration process, a staff person will manage the process of 
participant registrations, periodically checking to make sure that payments are being 
made, managing the wait list when they exceed their maximum number of participants. 

• During the day of the event, organizers will check-in each attendee on-site to keep 
track of who's actually attending and who is a no-show. This will also help determine at 
the end of the event who has paid and who still owes fees. 

• After the event, the Director will create reports about the number of attendees, and 
total fees received and other event details for a report to give to the organization's 
funders 



PLANNING WITH CIVIENGAGE 

CiviEngage packages a set of custom data groups and fields, reports, and other features for 
use in civic engagement and community organizing work. This chapter will describe the general 
concepts and planning needed to use CiviEngage effectively. 

WHAT YOU NEED TO KNOW 

The following are concepts, custom fields and values to keep in mind when preparing to use 
CiviEngage. 

Campaign Source Code 

Campaign Source Codes are descriptive values used to identify related activities, events, 
contributions, and memberships and map how these activities and transactions are linked 
together. Campaign Source Codes are also useful for identifying these sets of activities or 
transactions as part of a larger campaign, project, or program. 

For example, an organization is conducting a door knock canvass around a particular issue 
during a specific range of dates. The organization may want to use campaign source codes to 
link together the activities (where responses to door knock canvass questions are captured), 
the event (the door knock canvass campaign itself), and any contributions made during the 
canvass to be able to analyze the effectiveness of the campaign. 

Activity, Event, Contribution, Participant, and Membership records each contain a custom field 
to store a Campaign Source Code, that all share a common option list where Campaign Source 
Code values can be added and edited. 

Your organization can establish a standard method for creating new Campaign Source Codes 
so that the codes are consistent and easy to sort and understand at a glance. For example, 
you can specify that annual campaigns always include the year at the either the beginning or 
the end of the Campaign Source Code, not both, so that you don't wind up with "2009 Annual 
Campaign" and "Annual Campaign 2010." 

Issue Interests 

Issue Interests are issues that your organization works on or tracks. They are included in 
CiviEngage as a single option list shared across multiple contexts: 

• Grassroots Info: Issue Interests for individuals 

• Media Issue Interests for media contacts 

• Funder Issue Interests for funders 

• Grant Info: Funding Areas for organizations 

It is important to remember that despite appearing with different labels in these different 
contexts, you are still dealing with just one shared list of options. 

In planning to use CiviEngage you should come up with a list of distinct issues that are 
important to your organization and that you will want to utilize when tracking individuals' 
interest in your organization's work, the issues that your media contacts may be interested in 
covering, funders' general interests and the specific areas of work included in particular grants. 

Volunteer Interest 



Volunteer interests are activities that your organization's volunteers can take on and 
participate in; you can indicate each individual's interest in participating in these ways. They 
are included in CiviEngage as an option list. In planning to use CiviEngage you should establish a 
list of your organization's current volunteer activities as well as any activities that you are 
planning to launch in the future. Some examples of volunteer interests are canvassing, phone 
banking, and tabling. 

Cleaning your Address Data 

Cleaning your address data means standardizing addresses to conform to the conventions 
defined by the United States Postal Service's Standards for Addresses. Standardizing how 
addresses are entered into CiviCRM will allow for more accurate search results when searching 
by address and is essential to generate accurate Walk List reports. CiviCRM will parse 
addresses based on the USPS standards. To find out more about how Address Parsing is 
handled and used in CiviCRM, refer to the Address Parsing chapter of this book. When adding 
or editing contacts you will be entering or editing address elements including street number, 
street name, and Apt/Unit/Suite number according to these standards. 

When planning to import pre-existing data into CiviCRM for use in CiviEngage it is essential that 
you plan to clean up address data before importing. 

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 
at http://pe.usps.com/text/pub28/welcome.htm . 

TRACKING CIVIC ENGAGEMENT AND CAMPAIGNS 

CiviEngage is designed to manage interactions with constituents around an organization's civic 
engagement and base-building work, such as door knock canvassing and phone banking. There 
are several concepts and details to consider when preparing for these types of campaigns. 

Working with Your Universe of Contacts 

In preparing for your campaign, you will need to identify the audiences you will be targeting for 
your door knock canvass or phone bank in CiviCRM. CiviCRM uses Smart Groups and regular 
Groups as the mechanisms to target specific groups of contacts. Here are a couple of 
examples of how you can use Smart Groups and regular Groups for targeting during your 
campaign: 

• You can use Smart Groups to identify contacts you want to target based on specific 
criteria, such as voter demographics, issue interests, primary language spoken, etc. 

• You can track voter demographics about your contacts using the custom data group 
called Voter Info 

• You can use Groups to identify contacts who subscribe to a particular newsletter or 
issue to do an email blast about your campaign. 

• You can then use these Smart Groups and regular Groups to generate your walk list or 
phone bank list. 

Learn more about working with Smart Groups and regular Groups in the "Tags and Groups" 
chapter of this book. 

Preparing a Campaign Event 

To prepare a campaign event in CiviCRM, there are several setup items you may want to 
consider: 



• Define a specific Campaign Source Code for your event. This Campaign Source Code will 
be used for the event and the activity which holds the individual responses gathered 
during the door knock canvass or phone bank campaign. 

• When you set up your event with the Event Type set to "Campaign" you can record 
the questions being asked during the campaign in the Event Campaign Details area. 

• Decide how you want to identify participants in the campaign event. Maybe you only 
want to identify the staff and volunteers who will be involved in conducting the door 
knock canvass or phone bank. Maybe you'll want to add the targeted contacts as 
participants. Activities will be used to record the responses of each individual contacted 
during the campaign as well as the campaign source code related to the campaign, so it 
may not be necessary to add these contacts to the event. In either case, it is 
recommended to also record the Campaign Source Code in the participant's record in 
the Participant Info area. 

• When capturing responses from each individual during the campaign, consider how you 
plan on getting the data back into CiviCRM. If the plan is to enter data one contact at a 
time, which may make sense for phone banking, you will need to record the response in 
the individual's activity record, with the Activity Type of "Door Knock" or "Phone" in 
the Walk List Responses or Call List Responses area. But if you plan on entering 
batches of data at a time, then you will need to plan to import the responses using the 
Import Activities function. 

Working with Voter History 

When using CiviEngage, plan how you will manage voter history and other voter information 
collected during a voter engagement or electoral cycle. Many organizations have access to a 
voter file from which they manage all their voter engagement work outside of CiviCRM. Once 
the voter engagement or electoral campaign is over and voter information is updated with 
who voted and other demographics, organizations most often will only want to keep 
information on the actual contacts they made during the campaign. In this case, only those 
selected records from the voter file and additional voter information, such as responses to 
specific electoral campaign questions, will be imported and maintained in CiviCRM. These voter 
records then become contacts that organizers will continue to engage and target with base- 
building efforts. 

If you wish to collect voter contacts with their demographics, history, and additional 
information, first import voter contacts (with their contact information and demographics) into 
the Voter Info custom group. Then import additional information as Activities, such as 
responses to electoral campaign canvass questions. 

MOBILIZING INDIVIDUALS TO ATTEND AN EVENT 

The Participant Info custom data group that comes with CiviEngage contains fields that hold 
information about prospective event participants, including a history of interactions between 
your organization and prospective participants. Use this information (such as needs for 
childcare or rides) to bring these individuals to your events. Tracking the history of your 
organization's contact with individuals around events such as an annual membership meeting, 
a direct action, or leadership training can help you to understand the effectiveness of your 
outreach methods and determine how committed or engaged an individual is based on if the 
individual actually attends events after multiple contacts. 

This feature is mostly useful for organizers or staff who have a list of individuals they are 
recruiting to attend an event through multiple phone calls or face-to-face meetings. The 
following CiviCRM tasks could be used to mobilize individuals: 



1. Conduct a basic or advanced search or use Groups and Smart Groups to create a list of 
the contacts you want to mobilize or invite to the event. 

2. From the search results or Group Contacts screen, you can add the list of contacts to 
the event by selecting Add Contacts to Events from the Actions list. To find out more 
about how to add contacts to events, refer to the Managing Participants chapter in the 
Events section in this book. 

3. Once you add the contacts to the event, you can enter participant information or 
responses from multiple interactions in the Participant Info area in a contact's 
participant record. You can either enter information for one participant by editing the 
participant record itself, or you can add information for a list of participants at one time. 
For example, if you plan to call through your list by viewing the participant list from the 
event listing, you could use Batch Update Participants Via Profile and select one of 
the following custom profiles provided by CiviEngage: 

• Update Event Invite Responses - to record responses from multiple contacts with the 
participant. 

• Update Participant Info - to record general information about participants, such as if 
they need childcare or rides to the event. 

TRACKING FUNDERS AND FOUNDATIONS 

You can track information about and due dates for grant proposals, letters of inquiries, and 
reports for funders by adding an activity related to the funder's contact record and choosing 
from the Proposal, Letter of Inquiry, or Report activity types. 

You can also tailor information about an individual funder, such as their funding areas and 
issue interests, using the Funder Info custom group. In order to view the Funder Info tab, you 
will need to use the Individual sub-contact type, Funder, when you create a new contact that 
is identified as a funder. 

You can tailor information about a foundation (organization record), such as their program 
areas for funding, using the Grant Info custom group. 

TRACKING MEDIA CONTACTS 

As part of civic engagement and community organizing work, it can be useful to track 
information about your media contacts in CiviCRM, especially if you want to know which media 
contacts or outlets are interested in your organization's issues, or have written articles about 
your work, or for identifying who to contact when you want to publicize the work the 
organization is undertaking. 

You can tailor information about an individual media contact, such as their media type (e.g., 
TV, Newspaper, Photographer, etc.), issue interests and beat using the Media Info - Ind 
custom group. Use the Individual sub-contact type, Media Contact, when you create a new 
contact for a media contact. You can then view and edit the Media Info - Ind tab. 

You can also tailor information about a media outlet (organization) such as their media type 
(e.g., TV, Newspaper, Magazine, etc.) using the Media Info - Org custom group. As with the 
individual media person, use the Organization sub-contact type, Media Outlet, when you 
create a new contact for a media outlet. You can then view and edit the Media Info - Org 
tab. 

TRACKING ELECTED OFFICIALS 

Identifying and collecting information about your elected officials could be useful for your 
community organizing and civic engagement work. You may want to know who is an elected 
official in a specific district, or who to contact on their staff, such as the scheduler, or 
spokesperson. 



You can tailor information about an individual elected official, such as their elected position 
(e.g., city council, Senate, etc.) and their role using the Elected Info custom group. Use the 
Individual sub-contact type, Elected Official, when you create a new contact for an elected 
official. You can then view and edit the Elected Info tab. Remember that staffers, schedulers, 
or spokespeople for an elected official can be entered as the Elected Official subtype. 

REPORTING AND ANALYSIS 

There are two reports packaged with CiviEngage: Walk List and Phonebank List. In addition, 
the Activity Report is enhanced to filter custom activity fields such as those associated with 
the custom group Call List Responses and Walk List Responses. 

The Walk List report allows you to view, print, or export an individual's contact information 
and demographics such as Member Type, Sex, Age, Party Registration, Voter history, along 
with response codes and notes where a volunteer can collect responses during a door knock 
canvass. 

The Phonebank List report is similar to the Walk List report except that this report is used 
exclusively during a phonebank and contain response codes pertaining to phone responses. 

The Walk List and Phonebank List reports are used to collect information during a campaign to 
later be imported or batch entered back into CiviCRM. 

The Activity Report is enhanced to allow you to search, view, print, or export for specific 
responses from a door knock canvass or phonebank campaign. Use this report not only to 
analyze the effectiveness of your campaign (e.g., how many people you contacted and 
collected responses from) but also to analyze responses from your constituency around an 
issue, or to determine whether individuals may become more involved with your 
organization. 

Disabling vs. Deleting Custom Data 

If you decide you don't need to use or view particular custom groups, fields, or values, we 
strongly recommend that you disable the group, field, or value rather than delete them. The 
Walk List and Phonebank List reports rely on these fields, so deleting certain custom data 
could potentially "break" the reports. 



CONFIGURATION 

You will need to configure both Drupal and CiviEngage to use the module. 

CONFIGURING CIVICRM FOR CIVIENGAGE 

CiviEngage can be configured using the following CiviCRM core features: 
Custom Data Groups 

Configure custom data groups and fields to track voter demographics, issue interests, 
leadership levels, volunteer interests, and information about funders, media contacts, and 
elected officials. 

Contact Subtypes 

CiviEngage takes advantage of CiviCRM contact subtypes to expose custom data groups 
associated only with specific subtypes. The following are new contact subtypes: 

Individual subtypes: 

• Media Contact - will expose a contact tab containing information specific to media 
contacts, such as their media type (e.g. Newspaper, Radio, TV, etc.), their "Beat," and 
the media issue interests 

• Elected Official - will expose a contact tab containing information specific to elected 
officials, such as their elected level (e.g. City Council, Senate, etc.) and the role (e.g. 
scheduler, spokesperson, etc.) 

• Funder - will expose a contact tab containing information specific to funders, such as 
their program areas and their issue interests. 

Organization subtypes: 

• Media Outlet - will expose a contact tab containing information about their type of 
media, such as TV, Radio, Wire, Newspaper, Magazine, etc. 

Campaign Source Codes 

CiviEngage uses Campaign Source Codes that you can tailor to describe and track related 
activities, events, event participants, contributions, or memberships. Campaign Source Codes 
can be used to describe a group of related activities, events, contributions, or memberships 
for a specific campaign, project, or program. 

Note: A "Campaign" does not necessarily mean a formal campaign, but can also generally be 
defined as a specific project, program, or organizing activity. 

Door Knock Canvass and Phone Bank Tracking 

• Events used for Door Knock Canvass or Phone Bank - Use the Campaign Event Type to 
expose Event custom fields that allows you to store up to four specific questions being 
asked during a door knock canvass or phone bank. 

• Activities used to Collect Responses from Door Knock Canvass or Phone Bank 
Campaigns - Use the Door Knock and Phone Call Activity Types to expose custom 
fields where you can collect an individual's responses during a door knock canvass or 
phone bank. 

Reports 



• Walk List Report - view, print or export certain demographic and other constituent 
information in a specific geographic area to collect responses to be used during a door 
knock canvass. The Walk List Report takes advantage of the optional address parsing 
feature to build the report. 

• Call List Report - view, print or export certain demographic and other constituent 
information along with an area to collect responses to be used during a phone bank. 

• Activity Report - includes filters for activity custom fields so that you can build a report 
of specific activities based on criteria about your constituency, such as creating a report 
to analyze particular responses from a door knock canvass or phone bank. 

Grant Proposal and Report Tracking 

CiviEngage uses the Proposal, Letter of Inquiry and Report Activity Types to expose custom 
fields to track information and schedules for proposals, letters of inquiries and reports related 
to an individual funder or foundation. 

Custom Profiles 

CiviEngage configures several custom profiles for easier batch updating of individual or 
organization information, such as voter demographics, issue interests, volunteer interests, or 
event participant information. To learn more about profiles, please refer to the "Profiles" 
section of the book. 

CONFIGURING CIVIENGAGE 

When you install CiviEngage a number of custom fields are automatically created. These fields 
are designed to support your community organizing work. Most of these fields are multiple 
choice fields which have been pre-populated with sample options. Before you start using 
CiviEngage, you need to review and modify the supplied options to meet your needs. 

Begin by going to Administer -> Customize -> Custom Data in the navigation menu. In the 
following list bolded items are Group Header entries in the Custom Data screen. The bulleted 
items are custom fields under those Group Headers that have been added by CiviEngage; the 
other fields under these group headers are standard to CiviCRM. The choices for these custom 
fields should be edited before you use CiviEngage. You should add, delete, or edit the available 
options for each custom field to make them better fit your organization's needs. 

Communications Details 

• Best Time to Contact 

Voter Info 

All of the fields in this custom data group are added by CiviEngage, so you should review and 
edit them all to suit your needs. You may also want to add specific local voter fields that apply 
to you. 

Constituent Info - Individuals 

• Constituent Type 

• Staff Responsible - note that the values for this field are also used for Event Contact 
Person. Replace the sample names in the list with your staff, member or volunteer 
coordinators, and other folks that have individuals assigned to them. 

• How Started - edit this list to fit the ways in which members are brought into your 
organization. 

Grassroots Info 



• Member Status - three status choices included by default. Think about other member 
statuses that might work for your organization and add or remove as needed. 

• Leadership Level - The default options for tracking an individual's leadership level within 
your organization are 1-5. Change this to match however your organization tracks this 
information. 

• Issue Interest - this custom field uses the same set of options as the Funding Areas and 
Funder Issue Interest fields. It is a list of issues that your organization works on or 
tracks. 

• Volunteer Interests - a list of volunteer activities that your members can take on. 

Constituent Info - Organizations 

• Constituent Type - Org 
Grant Info 

• Funding Areas - this custom field uses the same set of options for Issue Interest and 
Funder Issue Interest. 

Participant Info 

• Participant Campaign Code - this custom field uses the same set of options as the 
Contribution Campaign Code, Event Campaign Code, Activity Campaign Code and 
Membership Source Code fields. Delete the example campaigns and add your own. This 
is the mechanism CiviEngage uses to connect a contact's participation across all these 
different actions. For example, a Campaign called "House Party 10-1-2010" could have an 
Event tied to it, a participant of that Event tied to it, an activity when an organizer calls 
a contact inviting them to attend an Event, a membership entry when they become 
members at the Event and a contribution when they pay their dues. 

Contribution Source 

• Contribution Campaign Code - see Participant Campaign Code. 

• Contribution Campaign Method - this custom field uses the same set of options as 
Membership Source Campaign. Add different types of interactions or locations where 
you would be engaging potential members and donors. 

Event Details 

• Event Contact Person - also used for Staff Responsible. Add all appropriate people to 
this list. 

• Event Campaign Code - see Participant Campaign Code. 

Activity Source Details 

• Activity Campaign Code - see Participant Campaign Code. 

Organizational Details 

This custom group is used to store information that is specific to organizations. There is only 
one example currently. 

• Rating - if you need to evaluate organizations in some way, change the options to reflect 
that. 

Demographics 



• Ethnicity 

• Primary Language - this custom field uses the same set of options as Secondary 
Language. Only one entry can be selected for each contact for this field. 

• Secondary Language - also used for Primary Language, but as many choices as needed 
can be checked. 

Media Info - Org 

This custom group is only applicable to the New Media Outlet contact subtype. 

• Media Type - Org - this custom field uses the same set of options as Media Type - Ind: 
TV, Radio, Wire, Newspaper, Magazine 

Media Info - Ind 

This custom group is only applicable to the New Media Contact contact subtype. 

• Media Type - Ind - this custom field uses the same set of options as Media Type - Org 

• Beat - this refers to the general category of topics that a media contact covers, such as 
local government, education, neighborhoods, religion, labor, etc. 

• Media Issue Interest - uses the same option list as Issue Interest. As you come to know 
a reporter, you will learn the issues they are particularly interested in, even if it differs 
from their assigned beat. 

Elected Info 

This custom group is only applicable to the New Elected Official contact subtype. 

• Elected Level - the governmental body the individual is part of (City Council, state 
legislature, mayor, etc.) 

• Role - Whether the contact is the elected official, or the official's staff, spokesperson, 
etc. 

Funder Info 

This custom group is only applicable to the New Funder contact subtype. 

• Funder Issue Interest - this custom field uses the same set of options as Issue Interest 
and Funding Areas. 

Membership Source Details 

• Membership Source Code - Uses the same codes as the Participant Campaign Code and 
Contribution Campaign Code. 

• Membership Source Campaign - also used for contributions. Add different types of 
interactions or locations where you would be engaging potential members and donors. 



ESSENTIAL TASKS 

This chapter provides instructions on how to do some of the common tasks associated with 
the CiviEngage module. 

PRINTING A WALK LIST 

CiviEngage offers a report that allows you to easily print walk lists for folks who are doing 
canvassing, Get Out the Vote (GOTV) or other door knocking activities. 

1. If you want to use Groups or Smart Groups to develop your walk list, be sure to create 
the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the walk list report. Choose whether you want the Country or Email field to 
display. 

4. Scroll down to the "Set Filters" section. You must select a filter to obtain results. All 
your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the report results, but if you click on "Print Preview" you will see your walk list. 
You can use your browser's Print Preview feature to see the walk list on a per-page 
basis. 

PRINTING A PHONE LIST 

CiviEngage offers a report that allows you to easily print phone lists for folks who are doing 
phone banks or other mass phoning activities. 

1. If you want to use Groups or Smart Groups to develop your phone list, be sure to 
create the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the phone list report. Choose the columns you want to display from the 
template screen. 

4. Scroll down to the "Set Filters" section. You must select a filter in order to obtain 
results. All your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the results but if you click on "Print Preview" you will see your phone list. You can 
now use your browser's Print Preview feature to see the phone list on a per-page basis. 

CREATE A CAMPAIGN SOURCE CODE 

In order to use CiviEngage effectively, you need to create "campaigns" that you connect all 
your activities to. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Participant Info in the list and click the corresponding "View and Edit Custom Fields" 
link. This gives you a list of Custom Fields. 

3. Find Participant Campaign Code and click the "Edit Multiple Choice Options" link. Now you 
are seeing a list of the interests. 

4. Scroll down and click on "New Option" and add your new campaign. 

Please note that this new campaign code will now be available for Event, Membership and 
Contribution Campaign Codes as well as in the Participant Campaign Code that it was just 
created in. 

ADD AN ISSUE INTEREST 



To better understand and track the areas that your members and constituencies are 
interested in working on, CiviEngage provides a field that collects this information. Customize 
this list to meet the needs of your particular organization. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Grassroots Info in the list and click on the corresponding "View and Edit Custom 
Fields" link. This gives you a list of Custom Fields. 

3. Find Issue Interest and click the "Edit Multiple Choice Options" link. Now you are seeing a 
list of the interests. 

4. Scroll down and click "New Option" and add your new interest. 

Please note that this new issue will also appear in Funding Areas and Funder Issue Interest as 
well as in the Issue Interest that it was just created in. 

TRACK WALK LIST/CALL LIST RESPONSES 

Responses to the questions your canvassers or phone bankers ask are tracked in an 
individual's activity record. The text of the questions are tracked in the event record. In order 
to properly configure this, start with creating the event. 

1. Click on Events -> New Event. 

2. Choose Campaign for your Event Type, which will let you see the Event Campaign Details 
section. 

3. Scroll down to the Event Campaign Details section and add the text to the questions for 
this particular campaign. 

4. You will also want to add an Event Campaign Code, which is in the Event Details section. 

Next you would go to a contact record to create a "Door Knock" or "Phone Call" activity and 
finish configuring this functionality. 

1. Go to a contact's record and click on "new activity." 

2. Choose "Phone Call" or "Door Knock" and you will get the Activities screen. 

3. Scroll down and click on the Call List Responses section. 

4. Now you can record the responses. 

5. You then add the Activity Campaign Code in the Activity Source Details section. Make 
sure you choose the same campaign as you did for the Event. 
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PRINT AN ACTIVITY REPORT 

One of the features of CiviEngage is the ability to track the different activities that your 
members are engaged in. Use the activity report to better understand what your members 
are doing. 



1. Click on Reports -> Create Reports from Template . 

2. Choose the Activity Report. This brings up the Activity Report Template. You are now 
looking at all the options available for printing a report based on the activities CiviEngage 
offers that your contacts are engaged in. 

3. The first section lists the columns that are available for your report. Use the check 
boxes to decide what information you want your report to show. The default values are 
Assignee Contact Name , Target Contact Name , Activity Type , Subject, Activity Date and 
Activity Status . You can choose columns from Walk List Responses, Leadership Level 
(from Activities), Call List Responses, Proposal Info or Activity Source Details. 

If, for example, you want a report of Walk List Responses from a specific campaign, you 
would check boxes from the Walk List Responses section and choose the Activity 
Campaign Code from the Activity Source Details section. Please note that the default 
value for Activity Date is "this month." If you want a different range of dates you have 
many options. Click on "this month" and you will see all the options available. Included is 
Date Range, where you can choose a specific range of dates. 

4. The next section allows you to group your data by the Source Contact (the default 
value), Activity Date or Activity Type . Check the appropriate box for your report. 

5. The final section is for filtering your data. Here you can choose data from any of the 
activity fields that CiviEngage offers. 

To continue our example, you might choose to include data where the first two Walk 
List questions were answered yes. Choose Y in the appropriate boxes and scroll down to 
the Activity Source Detail section and choose the appropriate Activity Campaign Code . 
Click Preview Report and view your results. 

6. Once you have your results, you have a number of options. You can "Preview" the 
report, "Preview" the PDF of the report, "Preview" the CSV (export your report into a 
spreadsheet), or "Add the contacts to a group." 

SEARCH FOR ACTIVITIES 

The are a number of ways to search for the activities that you create using CiviEngage: 

• Run a report, as explained above 

• Use the Find Activities search option 

• Use the CiviCRM Advanced Search 

• Run an Activity Search, which is in Custom Searches. 

Using the Find Activities search option 

1. Click on Search -> Find Activities . 

2. You are presented with a number of search criteria options. You can enter the name or 
email address of a contact in the database. You can choose one or more activity types. 
You can add a range of dates during which activities happened. You can search for 
contacts in specific Activity Roles: With, Created By and Assigned to. You can look for 
specific subjects, test activities or by the status of the activity. Each criterion you select 
will narrow your search results. 

3. Click Search and you will get to the Search Results screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using Advanced Search to find Activities 



1. Click on Search -> Find Contacts - Advanced Search . 

2. Scroll down to the Activities section and click on it. Here you find all the options available 
in CiviEngage for activities. 

3. Once you choose your search options and click Search you will get to the Search Results 
screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using the Custom Search: Activity Search 

1. Click on Search -> Custom Searches... -> Activity Search . 

2. You are presented with different criteria by which you can search for information. Enter 
your search terms and click Search. 

3. The Search Results provides the Name of the person, the Status, Type and Subject of 
the Activity and who assigned the activity. You also have a button for viewing and 
editing each activity record. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 
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WHAT IS CIVIMEMBER? 



CiviMember allows you to track and manage membership for one or more organisations. You 
can define different membership types for each organisation. CiviCRM provides tools to track 
contacts through the membership cycle, and also handles the renewal process. 

A central aim of CiviMember (much like other CiviCRM components) is the aim to automate 
membership administration as much as possible. 

REAL WORLD SCENARIOS 

The Atlantis State Public Transit Association (ASPTA) is useful as a case study for thinking 
about how to apply memberships. They have four membership categories it must configure in 
CiviCRM: 

• Regular Members: Public transit systems. There are three tiered dues levels within this 
category, based on the size of the system. Membership is organization-based, and all 
employees receive access to member benefits, such as discounted rates at Association 
events. 

• Affiliate Members: Businesses providing goods and services to the transit industry, 
such as bus and rail car manufacturers, engineers and consultants, parts and component 
manufacturers, etc. Membership dues are a flat rate for all Affiliate Members. 
Membership is organization-based, and all employees receive access to member 
benefits, such as discounted rates at Association events. 

• Associate Members: Students, government representatives, public interest groups, 
research institutions, and other interested parties. Membership dues are a flat rate for 
all Associate Members. Membership is individual-based. 

• Honorary Members: Retired transit system executives and others who have made a 
notable contribution to the industry and Association. No membership dues; lifetime 
period. Membership is individual-based. 

As the ASPTA CiviCRM administrator configures the membership types, she creates three 
separate types for the Regular Member category to account for the three dues levels. The 
duration is one year, beginning on January 1, with a rollover date of October 1. In this way she 
accounts for new members who join very late in the year and are not able to fully benefit 
from their membership — the membership extends through December 31 the following year. 

The Atlantis State Public Transit Association's (ASPTA) Membership Committee begins a 
focused outreach to non-member public transit systems (Regular Member category) and non- 
member businesses working in the public transit industry (Affiliate Member category). They 
want their members to renew online and pay through a credit card. 

To accomplish this, they create a membership signup/renewal contribution page. The 
membership join (signup) page will be available to all website visitors. The membership renewal 
page will be visible to members after they login to the members-only section. 

After completing configuration of their membership signup-renewal page, ASPTA creates a 
menu link to expose the form and begin their online membership recruitment effort. 
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PLANNING WITH CIVIENGAGE 

CiviEngage packages a set of custom data groups and fields, reports, and other features for 
use in civic engagement and community organizing work. This chapter will describe the general 
concepts and planning needed to use CiviEngage effectively. 

WHAT YOU NEED TO KNOW 

The following are concepts, custom fields and values to keep in mind when preparing to use 
CiviEngage. 

Campaign Source Code 

Campaign Source Codes are descriptive values used to identify related activities, events, 
contributions, and memberships and map how these activities and transactions are linked 
together. Campaign Source Codes are also useful for identifying these sets of activities or 
transactions as part of a larger campaign, project, or program. 

For example, an organization is conducting a door knock canvass around a particular issue 
during a specific range of dates. The organization may want to use campaign source codes to 
link together the activities (where responses to door knock canvass questions are captured), 
the event (the door knock canvass campaign itself), and any contributions made during the 
canvass to be able to analyze the effectiveness of the campaign. 

Activity, Event, Contribution, Participant, and Membership records each contain a custom field 
to store a Campaign Source Code, that all share a common option list where Campaign Source 
Code values can be added and edited. 

Your organization can establish a standard method for creating new Campaign Source Codes 
so that the codes are consistent and easy to sort and understand at a glance. For example, 
you can specify that annual campaigns always include the year at the either the beginning or 
the end of the Campaign Source Code, not both, so that you don't wind up with "2009 Annual 
Campaign" and "Annual Campaign 2010." 

Issue Interests 

Issue Interests are issues that your organization works on or tracks. They are included in 
CiviEngage as a single option list shared across multiple contexts: 

• Grassroots Info: Issue Interests for individuals 

• Media Issue Interests for media contacts 

• Funder Issue Interests for funders 

• Grant Info: Funding Areas for organizations 

It is important to remember that despite appearing with different labels in these different 
contexts, you are still dealing with just one shared list of options. 

In planning to use CiviEngage you should come up with a list of distinct issues that are 
important to your organization and that you will want to utilize when tracking individuals' 
interest in your organization's work, the issues that your media contacts may be interested in 
covering, funders' general interests and the specific areas of work included in particular grants. 

Volunteer Interest 



Volunteer interests are activities that your organization's volunteers can take on and 
participate in; you can indicate each individual's interest in participating in these ways. They 
are included in CiviEngage as an option list. In planning to use CiviEngage you should establish a 
list of your organization's current volunteer activities as well as any activities that you are 
planning to launch in the future. Some examples of volunteer interests are canvassing, phone 
banking, and tabling. 

Cleaning your Address Data 

Cleaning your address data means standardizing addresses to conform to the conventions 
defined by the United States Postal Service's Standards for Addresses. Standardizing how 
addresses are entered into CiviCRM will allow for more accurate search results when searching 
by address and is essential to generate accurate Walk List reports. CiviCRM will parse 
addresses based on the USPS standards. To find out more about how Address Parsing is 
handled and used in CiviCRM, refer to the Address Parsing chapter of this book. When adding 
or editing contacts you will be entering or editing address elements including street number, 
street name, and Apt/Unit/Suite number according to these standards. 

When planning to import pre-existing data into CiviCRM for use in CiviEngage it is essential that 
you plan to clean up address data before importing. 

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 
at http://pe.usps.com/text/pub28/welcome.htm . 

TRACKING CIVIC ENGAGEMENT AND CAMPAIGNS 

CiviEngage is designed to manage interactions with constituents around an organization's civic 
engagement and base-building work, such as door knock canvassing and phone banking. There 
are several concepts and details to consider when preparing for these types of campaigns. 

Working with Your Universe of Contacts 

In preparing for your campaign, you will need to identify the audiences you will be targeting for 
your door knock canvass or phone bank in CiviCRM. CiviCRM uses Smart Groups and regular 
Groups as the mechanisms to target specific groups of contacts. Here are a couple of 
examples of how you can use Smart Groups and regular Groups for targeting during your 
campaign: 

• You can use Smart Groups to identify contacts you want to target based on specific 
criteria, such as voter demographics, issue interests, primary language spoken, etc. 

• You can track voter demographics about your contacts using the custom data group 
called Voter Info 

• You can use Groups to identify contacts who subscribe to a particular newsletter or 
issue to do an email blast about your campaign. 

• You can then use these Smart Groups and regular Groups to generate your walk list or 
phone bank list. 

Learn more about working with Smart Groups and regular Groups in the "Tags and Groups" 
chapter of this book. 

Preparing a Campaign Event 

To prepare a campaign event in CiviCRM, there are several setup items you may want to 
consider: 



• Define a specific Campaign Source Code for your event. This Campaign Source Code will 
be used for the event and the activity which holds the individual responses gathered 
during the door knock canvass or phone bank campaign. 

• When you set up your event with the Event Type set to "Campaign" you can record 
the questions being asked during the campaign in the Event Campaign Details area. 

• Decide how you want to identify participants in the campaign event. Maybe you only 
want to identify the staff and volunteers who will be involved in conducting the door 
knock canvass or phone bank. Maybe you'll want to add the targeted contacts as 
participants. Activities will be used to record the responses of each individual contacted 
during the campaign as well as the campaign source code related to the campaign, so it 
may not be necessary to add these contacts to the event. In either case, it is 
recommended to also record the Campaign Source Code in the participant's record in 
the Participant Info area. 

• When capturing responses from each individual during the campaign, consider how you 
plan on getting the data back into CiviCRM. If the plan is to enter data one contact at a 
time, which may make sense for phone banking, you will need to record the response in 
the individual's activity record, with the Activity Type of "Door Knock" or "Phone" in 
the Walk List Responses or Call List Responses area. But if you plan on entering 
batches of data at a time, then you will need to plan to import the responses using the 
Import Activities function. 

Working with Voter History 

When using CiviEngage, plan how you will manage voter history and other voter information 
collected during a voter engagement or electoral cycle. Many organizations have access to a 
voter file from which they manage all their voter engagement work outside of CiviCRM. Once 
the voter engagement or electoral campaign is over and voter information is updated with 
who voted and other demographics, organizations most often will only want to keep 
information on the actual contacts they made during the campaign. In this case, only those 
selected records from the voter file and additional voter information, such as responses to 
specific electoral campaign questions, will be imported and maintained in CiviCRM. These voter 
records then become contacts that organizers will continue to engage and target with base- 
building efforts. 

If you wish to collect voter contacts with their demographics, history, and additional 
information, first import voter contacts (with their contact information and demographics) into 
the Voter Info custom group. Then import additional information as Activities, such as 
responses to electoral campaign canvass questions. 

MOBILIZING INDIVIDUALS TO ATTEND AN EVENT 

The Participant Info custom data group that comes with CiviEngage contains fields that hold 
information about prospective event participants, including a history of interactions between 
your organization and prospective participants. Use this information (such as needs for 
childcare or rides) to bring these individuals to your events. Tracking the history of your 
organization's contact with individuals around events such as an annual membership meeting, 
a direct action, or leadership training can help you to understand the effectiveness of your 
outreach methods and determine how committed or engaged an individual is based on if the 
individual actually attends events after multiple contacts. 

This feature is mostly useful for organizers or staff who have a list of individuals they are 
recruiting to attend an event through multiple phone calls or face-to-face meetings. The 
following CiviCRM tasks could be used to mobilize individuals: 



1. Conduct a basic or advanced search or use Groups and Smart Groups to create a list of 
the contacts you want to mobilize or invite to the event. 

2. From the search results or Group Contacts screen, you can add the list of contacts to 
the event by selecting Add Contacts to Events from the Actions list. To find out more 
about how to add contacts to events, refer to the Managing Participants chapter in the 
Events section in this book. 

3. Once you add the contacts to the event, you can enter participant information or 
responses from multiple interactions in the Participant Info area in a contact's 
participant record. You can either enter information for one participant by editing the 
participant record itself, or you can add information for a list of participants at one time. 
For example, if you plan to call through your list by viewing the participant list from the 
event listing, you could use Batch Update Participants Via Profile and select one of 
the following custom profiles provided by CiviEngage: 

• Update Event Invite Responses - to record responses from multiple contacts with the 
participant. 

• Update Participant Info - to record general information about participants, such as if 
they need childcare or rides to the event. 

TRACKING FUNDERS AND FOUNDATIONS 

You can track information about and due dates for grant proposals, letters of inquiries, and 
reports for funders by adding an activity related to the funder's contact record and choosing 
from the Proposal, Letter of Inquiry, or Report activity types. 

You can also tailor information about an individual funder, such as their funding areas and 
issue interests, using the Funder Info custom group. In order to view the Funder Info tab, you 
will need to use the Individual sub-contact type, Funder, when you create a new contact that 
is identified as a funder. 

You can tailor information about a foundation (organization record), such as their program 
areas for funding, using the Grant Info custom group. 

TRACKING MEDIA CONTACTS 

As part of civic engagement and community organizing work, it can be useful to track 
information about your media contacts in CiviCRM, especially if you want to know which media 
contacts or outlets are interested in your organization's issues, or have written articles about 
your work, or for identifying who to contact when you want to publicize the work the 
organization is undertaking. 

You can tailor information about an individual media contact, such as their media type (e.g., 
TV, Newspaper, Photographer, etc.), issue interests and beat using the Media Info - Ind 
custom group. Use the Individual sub-contact type, Media Contact, when you create a new 
contact for a media contact. You can then view and edit the Media Info - Ind tab. 

You can also tailor information about a media outlet (organization) such as their media type 
(e.g., TV, Newspaper, Magazine, etc.) using the Media Info - Org custom group. As with the 
individual media person, use the Organization sub-contact type, Media Outlet, when you 
create a new contact for a media outlet. You can then view and edit the Media Info - Org 
tab. 

TRACKING ELECTED OFFICIALS 

Identifying and collecting information about your elected officials could be useful for your 
community organizing and civic engagement work. You may want to know who is an elected 
official in a specific district, or who to contact on their staff, such as the scheduler, or 
spokesperson. 



You can tailor information about an individual elected official, such as their elected position 
(e.g., city council, Senate, etc.) and their role using the Elected Info custom group. Use the 
Individual sub-contact type, Elected Official, when you create a new contact for an elected 
official. You can then view and edit the Elected Info tab. Remember that staffers, schedulers, 
or spokespeople for an elected official can be entered as the Elected Official subtype. 

REPORTING AND ANALYSIS 

There are two reports packaged with CiviEngage: Walk List and Phonebank List. In addition, 
the Activity Report is enhanced to filter custom activity fields such as those associated with 
the custom group Call List Responses and Walk List Responses. 

The Walk List report allows you to view, print, or export an individual's contact information 
and demographics such as Member Type, Sex, Age, Party Registration, Voter history, along 
with response codes and notes where a volunteer can collect responses during a door knock 
canvass. 

The Phonebank List report is similar to the Walk List report except that this report is used 
exclusively during a phonebank and contain response codes pertaining to phone responses. 

The Walk List and Phonebank List reports are used to collect information during a campaign to 
later be imported or batch entered back into CiviCRM. 

The Activity Report is enhanced to allow you to search, view, print, or export for specific 
responses from a door knock canvass or phonebank campaign. Use this report not only to 
analyze the effectiveness of your campaign (e.g., how many people you contacted and 
collected responses from) but also to analyze responses from your constituency around an 
issue, or to determine whether individuals may become more involved with your 
organization. 

Disabling vs. Deleting Custom Data 

If you decide you don't need to use or view particular custom groups, fields, or values, we 
strongly recommend that you disable the group, field, or value rather than delete them. The 
Walk List and Phonebank List reports rely on these fields, so deleting certain custom data 
could potentially "break" the reports. 



CONFIGURATION 

You will need to configure both Drupal and CiviEngage to use the module. 

CONFIGURING CIVICRM FOR CIVIENGAGE 

CiviEngage can be configured using the following CiviCRM core features: 
Custom Data Groups 

Configure custom data groups and fields to track voter demographics, issue interests, 
leadership levels, volunteer interests, and information about funders, media contacts, and 
elected officials. 

Contact Subtypes 

CiviEngage takes advantage of CiviCRM contact subtypes to expose custom data groups 
associated only with specific subtypes. The following are new contact subtypes: 

Individual subtypes: 

• Media Contact - will expose a contact tab containing information specific to media 
contacts, such as their media type (e.g. Newspaper, Radio, TV, etc.), their "Beat," and 
the media issue interests 

• Elected Official - will expose a contact tab containing information specific to elected 
officials, such as their elected level (e.g. City Council, Senate, etc.) and the role (e.g. 
scheduler, spokesperson, etc.) 

• Funder - will expose a contact tab containing information specific to funders, such as 
their program areas and their issue interests. 

Organization subtypes: 

• Media Outlet - will expose a contact tab containing information about their type of 
media, such as TV, Radio, Wire, Newspaper, Magazine, etc. 

Campaign Source Codes 

CiviEngage uses Campaign Source Codes that you can tailor to describe and track related 
activities, events, event participants, contributions, or memberships. Campaign Source Codes 
can be used to describe a group of related activities, events, contributions, or memberships 
for a specific campaign, project, or program. 

Note: A "Campaign" does not necessarily mean a formal campaign, but can also generally be 
defined as a specific project, program, or organizing activity. 

Door Knock Canvass and Phone Bank Tracking 

• Events used for Door Knock Canvass or Phone Bank - Use the Campaign Event Type to 
expose Event custom fields that allows you to store up to four specific questions being 
asked during a door knock canvass or phone bank. 

• Activities used to Collect Responses from Door Knock Canvass or Phone Bank 
Campaigns - Use the Door Knock and Phone Call Activity Types to expose custom 
fields where you can collect an individual's responses during a door knock canvass or 
phone bank. 

Reports 



• Walk List Report - view, print or export certain demographic and other constituent 
information in a specific geographic area to collect responses to be used during a door 
knock canvass. The Walk List Report takes advantage of the optional address parsing 
feature to build the report. 

• Call List Report - view, print or export certain demographic and other constituent 
information along with an area to collect responses to be used during a phone bank. 

• Activity Report - includes filters for activity custom fields so that you can build a report 
of specific activities based on criteria about your constituency, such as creating a report 
to analyze particular responses from a door knock canvass or phone bank. 

Grant Proposal and Report Tracking 

CiviEngage uses the Proposal, Letter of Inquiry and Report Activity Types to expose custom 
fields to track information and schedules for proposals, letters of inquiries and reports related 
to an individual funder or foundation. 

Custom Profiles 

CiviEngage configures several custom profiles for easier batch updating of individual or 
organization information, such as voter demographics, issue interests, volunteer interests, or 
event participant information. To learn more about profiles, please refer to the "Profiles" 
section of the book. 

CONFIGURING CIVIENGAGE 

When you install CiviEngage a number of custom fields are automatically created. These fields 
are designed to support your community organizing work. Most of these fields are multiple 
choice fields which have been pre-populated with sample options. Before you start using 
CiviEngage, you need to review and modify the supplied options to meet your needs. 

Begin by going to Administer -> Customize -> Custom Data in the navigation menu. In the 
following list bolded items are Group Header entries in the Custom Data screen. The bulleted 
items are custom fields under those Group Headers that have been added by CiviEngage; the 
other fields under these group headers are standard to CiviCRM. The choices for these custom 
fields should be edited before you use CiviEngage. You should add, delete, or edit the available 
options for each custom field to make them better fit your organization's needs. 

Communications Details 

• Best Time to Contact 

Voter Info 

All of the fields in this custom data group are added by CiviEngage, so you should review and 
edit them all to suit your needs. You may also want to add specific local voter fields that apply 
to you. 

Constituent Info - Individuals 

• Constituent Type 

• Staff Responsible - note that the values for this field are also used for Event Contact 
Person. Replace the sample names in the list with your staff, member or volunteer 
coordinators, and other folks that have individuals assigned to them. 

• How Started - edit this list to fit the ways in which members are brought into your 
organization. 

Grassroots Info 



• Member Status - three status choices included by default. Think about other member 
statuses that might work for your organization and add or remove as needed. 

• Leadership Level - The default options for tracking an individual's leadership level within 
your organization are 1-5. Change this to match however your organization tracks this 
information. 

• Issue Interest - this custom field uses the same set of options as the Funding Areas and 
Funder Issue Interest fields. It is a list of issues that your organization works on or 
tracks. 

• Volunteer Interests - a list of volunteer activities that your members can take on. 

Constituent Info - Organizations 

• Constituent Type - Org 
Grant Info 

• Funding Areas - this custom field uses the same set of options for Issue Interest and 
Funder Issue Interest. 

Participant Info 

• Participant Campaign Code - this custom field uses the same set of options as the 
Contribution Campaign Code, Event Campaign Code, Activity Campaign Code and 
Membership Source Code fields. Delete the example campaigns and add your own. This 
is the mechanism CiviEngage uses to connect a contact's participation across all these 
different actions. For example, a Campaign called "House Party 10-1-2010" could have an 
Event tied to it, a participant of that Event tied to it, an activity when an organizer calls 
a contact inviting them to attend an Event, a membership entry when they become 
members at the Event and a contribution when they pay their dues. 

Contribution Source 

• Contribution Campaign Code - see Participant Campaign Code. 

• Contribution Campaign Method - this custom field uses the same set of options as 
Membership Source Campaign. Add different types of interactions or locations where 
you would be engaging potential members and donors. 

Event Details 

• Event Contact Person - also used for Staff Responsible. Add all appropriate people to 
this list. 

• Event Campaign Code - see Participant Campaign Code. 

Activity Source Details 

• Activity Campaign Code - see Participant Campaign Code. 

Organizational Details 

This custom group is used to store information that is specific to organizations. There is only 
one example currently. 

• Rating - if you need to evaluate organizations in some way, change the options to reflect 
that. 

Demographics 



• Ethnicity 

• Primary Language - this custom field uses the same set of options as Secondary 
Language. Only one entry can be selected for each contact for this field. 

• Secondary Language - also used for Primary Language, but as many choices as needed 
can be checked. 

Media Info - Org 

This custom group is only applicable to the New Media Outlet contact subtype. 

• Media Type - Org - this custom field uses the same set of options as Media Type - Ind: 
TV, Radio, Wire, Newspaper, Magazine 

Media Info - Ind 

This custom group is only applicable to the New Media Contact contact subtype. 

• Media Type - Ind - this custom field uses the same set of options as Media Type - Org 

• Beat - this refers to the general category of topics that a media contact covers, such as 
local government, education, neighborhoods, religion, labor, etc. 

• Media Issue Interest - uses the same option list as Issue Interest. As you come to know 
a reporter, you will learn the issues they are particularly interested in, even if it differs 
from their assigned beat. 

Elected Info 

This custom group is only applicable to the New Elected Official contact subtype. 

• Elected Level - the governmental body the individual is part of (City Council, state 
legislature, mayor, etc.) 

• Role - Whether the contact is the elected official, or the official's staff, spokesperson, 
etc. 

Funder Info 

This custom group is only applicable to the New Funder contact subtype. 

• Funder Issue Interest - this custom field uses the same set of options as Issue Interest 
and Funding Areas. 

Membership Source Details 

• Membership Source Code - Uses the same codes as the Participant Campaign Code and 
Contribution Campaign Code. 

• Membership Source Campaign - also used for contributions. Add different types of 
interactions or locations where you would be engaging potential members and donors. 



ESSENTIAL TASKS 

This chapter provides instructions on how to do some of the common tasks associated with 
the CiviEngage module. 

PRINTING A WALK LIST 

CiviEngage offers a report that allows you to easily print walk lists for folks who are doing 
canvassing, Get Out the Vote (GOTV) or other door knocking activities. 

1. If you want to use Groups or Smart Groups to develop your walk list, be sure to create 
the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the walk list report. Choose whether you want the Country or Email field to 
display. 

4. Scroll down to the "Set Filters" section. You must select a filter to obtain results. All 
your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the report results, but if you click on "Print Preview" you will see your walk list. 
You can use your browser's Print Preview feature to see the walk list on a per-page 
basis. 

PRINTING A PHONE LIST 

CiviEngage offers a report that allows you to easily print phone lists for folks who are doing 
phone banks or other mass phoning activities. 

1. If you want to use Groups or Smart Groups to develop your phone list, be sure to 
create the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the phone list report. Choose the columns you want to display from the 
template screen. 

4. Scroll down to the "Set Filters" section. You must select a filter in order to obtain 
results. All your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the results but if you click on "Print Preview" you will see your phone list. You can 
now use your browser's Print Preview feature to see the phone list on a per-page basis. 

CREATE A CAMPAIGN SOURCE CODE 

In order to use CiviEngage effectively, you need to create "campaigns" that you connect all 
your activities to. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Participant Info in the list and click the corresponding "View and Edit Custom Fields" 
link. This gives you a list of Custom Fields. 

3. Find Participant Campaign Code and click the "Edit Multiple Choice Options" link. Now you 
are seeing a list of the interests. 

4. Scroll down and click on "New Option" and add your new campaign. 

Please note that this new campaign code will now be available for Event, Membership and 
Contribution Campaign Codes as well as in the Participant Campaign Code that it was just 
created in. 

ADD AN ISSUE INTEREST 



To better understand and track the areas that your members and constituencies are 
interested in working on, CiviEngage provides a field that collects this information. Customize 
this list to meet the needs of your particular organization. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Grassroots Info in the list and click on the corresponding "View and Edit Custom 
Fields" link. This gives you a list of Custom Fields. 

3. Find Issue Interest and click the "Edit Multiple Choice Options" link. Now you are seeing a 
list of the interests. 

4. Scroll down and click "New Option" and add your new interest. 

Please note that this new issue will also appear in Funding Areas and Funder Issue Interest as 
well as in the Issue Interest that it was just created in. 

TRACK WALK LIST/CALL LIST RESPONSES 

Responses to the questions your canvassers or phone bankers ask are tracked in an 
individual's activity record. The text of the questions are tracked in the event record. In order 
to properly configure this, start with creating the event. 

1. Click on Events -> New Event. 

2. Choose Campaign for your Event Type, which will let you see the Event Campaign Details 
section. 

3. Scroll down to the Event Campaign Details section and add the text to the questions for 
this particular campaign. 

4. You will also want to add an Event Campaign Code, which is in the Event Details section. 

Next you would go to a contact record to create a "Door Knock" or "Phone Call" activity and 
finish configuring this functionality. 

1. Go to a contact's record and click on "new activity." 

2. Choose "Phone Call" or "Door Knock" and you will get the Activities screen. 

3. Scroll down and click on the Call List Responses section. 

4. Now you can record the responses. 

5. You then add the Activity Campaign Code in the Activity Source Details section. Make 
sure you choose the same campaign as you did for the Event. 
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PRINT AN ACTIVITY REPORT 

One of the features of CiviEngage is the ability to track the different activities that your 
members are engaged in. Use the activity report to better understand what your members 
are doing. 



1. Click on Reports -> Create Reports from Template . 

2. Choose the Activity Report. This brings up the Activity Report Template. You are now 
looking at all the options available for printing a report based on the activities CiviEngage 
offers that your contacts are engaged in. 

3. The first section lists the columns that are available for your report. Use the check 
boxes to decide what information you want your report to show. The default values are 
Assignee Contact Name , Target Contact Name , Activity Type , Subject, Activity Date and 
Activity Status . You can choose columns from Walk List Responses, Leadership Level 
(from Activities), Call List Responses, Proposal Info or Activity Source Details. 

If, for example, you want a report of Walk List Responses from a specific campaign, you 
would check boxes from the Walk List Responses section and choose the Activity 
Campaign Code from the Activity Source Details section. Please note that the default 
value for Activity Date is "this month." If you want a different range of dates you have 
many options. Click on "this month" and you will see all the options available. Included is 
Date Range, where you can choose a specific range of dates. 

4. The next section allows you to group your data by the Source Contact (the default 
value), Activity Date or Activity Type . Check the appropriate box for your report. 

5. The final section is for filtering your data. Here you can choose data from any of the 
activity fields that CiviEngage offers. 

To continue our example, you might choose to include data where the first two Walk 
List questions were answered yes. Choose Y in the appropriate boxes and scroll down to 
the Activity Source Detail section and choose the appropriate Activity Campaign Code . 
Click Preview Report and view your results. 

6. Once you have your results, you have a number of options. You can "Preview" the 
report, "Preview" the PDF of the report, "Preview" the CSV (export your report into a 
spreadsheet), or "Add the contacts to a group." 

SEARCH FOR ACTIVITIES 

The are a number of ways to search for the activities that you create using CiviEngage: 

• Run a report, as explained above 

• Use the Find Activities search option 

• Use the CiviCRM Advanced Search 

• Run an Activity Search, which is in Custom Searches. 

Using the Find Activities search option 

1. Click on Search -> Find Activities . 

2. You are presented with a number of search criteria options. You can enter the name or 
email address of a contact in the database. You can choose one or more activity types. 
You can add a range of dates during which activities happened. You can search for 
contacts in specific Activity Roles: With, Created By and Assigned to. You can look for 
specific subjects, test activities or by the status of the activity. Each criterion you select 
will narrow your search results. 

3. Click Search and you will get to the Search Results screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using Advanced Search to find Activities 



1. Click on Search -> Find Contacts - Advanced Search . 

2. Scroll down to the Activities section and click on it. Here you find all the options available 
in CiviEngage for activities. 

3. Once you choose your search options and click Search you will get to the Search Results 
screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using the Custom Search: Activity Search 

1. Click on Search -> Custom Searches... -> Activity Search . 

2. You are presented with different criteria by which you can search for information. Enter 
your search terms and click Search. 

3. The Search Results provides the Name of the person, the Status, Type and Subject of 
the Activity and who assigned the activity. You also have a button for viewing and 
editing each activity record. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 
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WHAT IS CIVIMAIL 



This chapter gives a brief introduction to the possibilities for sending email with CiviCRM and 
gives an overview of some of the reasons that you would want to use CiviCRM for your 
mailings. 

There are two main ways to send email in CiviCRM: 

• the 'send mail to contacts' action 

• using CiviMail (CiviCRM's 'mass mailer') 

There are advantages and disadvantages for both methods. The first is quicker and easier. 
The second is more sophisticated and offers better options for reporting. 

Advantages for using CiviCRM to send mail include: 

• A shared address book is less work to maintain, and increases the chance of having the 
correct email for each of your contacts. 

• Every email sent is stored in the activity history of each of the recipients along the 
other activities. So you can see that John Doe made a donation 3 days after he received 
your April newsletter. 

• Everyone at your organisation can see who was sent a specific email, even if the person 
that sent it has left the organisation. 

• You can use templates to ensure your organisation visual identity and branding are 
consistently applied to all your email communications. 

• You can use "canned emails" for your most common emails (welcome emails, invitations 
to events, directions to your office, membership information, call for actions, etc). 

• You can send personalised mass emails using tokens. Personalised emails have better 
response rates. 

Advantages specific to CiviMail include: 

• bounced emails are handled automatically 

• recipients can manage their own subscriptions 

• statistics are avialble on who is reading your emails and what links they are clicking on 

CiviCRM also gives you the possibility to log incoming emails. CiviMail can be configured to 
automatically track replies by creating an autofile mailbox. Email sent to this mailbox is 
automatically converted into an activity and added to the right contact. 

Note that CiviMail has specific server requirements that are necessary in order to take 
advantage of the full functionality. Configuring the mail server and CiviMail is are system 
administrator tasks, which may also require professional assistance. You will also need to 
verify with your web hosting provider if they meet the configuration requirements, and verify 
they don't put limits on the number of emails you can send per day. 



PLANNING WITH CIVIENGAGE 

CiviEngage packages a set of custom data groups and fields, reports, and other features for 
use in civic engagement and community organizing work. This chapter will describe the general 
concepts and planning needed to use CiviEngage effectively. 

WHAT YOU NEED TO KNOW 

The following are concepts, custom fields and values to keep in mind when preparing to use 
CiviEngage. 

Campaign Source Code 

Campaign Source Codes are descriptive values used to identify related activities, events, 
contributions, and memberships and map how these activities and transactions are linked 
together. Campaign Source Codes are also useful for identifying these sets of activities or 
transactions as part of a larger campaign, project, or program. 

For example, an organization is conducting a door knock canvass around a particular issue 
during a specific range of dates. The organization may want to use campaign source codes to 
link together the activities (where responses to door knock canvass questions are captured), 
the event (the door knock canvass campaign itself), and any contributions made during the 
canvass to be able to analyze the effectiveness of the campaign. 

Activity, Event, Contribution, Participant, and Membership records each contain a custom field 
to store a Campaign Source Code, that all share a common option list where Campaign Source 
Code values can be added and edited. 

Your organization can establish a standard method for creating new Campaign Source Codes 
so that the codes are consistent and easy to sort and understand at a glance. For example, 
you can specify that annual campaigns always include the year at the either the beginning or 
the end of the Campaign Source Code, not both, so that you don't wind up with "2009 Annual 
Campaign" and "Annual Campaign 2010." 

Issue Interests 

Issue Interests are issues that your organization works on or tracks. They are included in 
CiviEngage as a single option list shared across multiple contexts: 

• Grassroots Info: Issue Interests for individuals 

• Media Issue Interests for media contacts 

• Funder Issue Interests for funders 

• Grant Info: Funding Areas for organizations 

It is important to remember that despite appearing with different labels in these different 
contexts, you are still dealing with just one shared list of options. 

In planning to use CiviEngage you should come up with a list of distinct issues that are 
important to your organization and that you will want to utilize when tracking individuals' 
interest in your organization's work, the issues that your media contacts may be interested in 
covering, funders' general interests and the specific areas of work included in particular grants. 

Volunteer Interest 



Volunteer interests are activities that your organization's volunteers can take on and 
participate in; you can indicate each individual's interest in participating in these ways. They 
are included in CiviEngage as an option list. In planning to use CiviEngage you should establish a 
list of your organization's current volunteer activities as well as any activities that you are 
planning to launch in the future. Some examples of volunteer interests are canvassing, phone 
banking, and tabling. 

Cleaning your Address Data 

Cleaning your address data means standardizing addresses to conform to the conventions 
defined by the United States Postal Service's Standards for Addresses. Standardizing how 
addresses are entered into CiviCRM will allow for more accurate search results when searching 
by address and is essential to generate accurate Walk List reports. CiviCRM will parse 
addresses based on the USPS standards. To find out more about how Address Parsing is 
handled and used in CiviCRM, refer to the Address Parsing chapter of this book. When adding 
or editing contacts you will be entering or editing address elements including street number, 
street name, and Apt/Unit/Suite number according to these standards. 

When planning to import pre-existing data into CiviCRM for use in CiviEngage it is essential that 
you plan to clean up address data before importing. 

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 
at http://pe.usps.com/text/pub28/welcome.htm . 

TRACKING CIVIC ENGAGEMENT AND CAMPAIGNS 

CiviEngage is designed to manage interactions with constituents around an organization's civic 
engagement and base-building work, such as door knock canvassing and phone banking. There 
are several concepts and details to consider when preparing for these types of campaigns. 

Working with Your Universe of Contacts 

In preparing for your campaign, you will need to identify the audiences you will be targeting for 
your door knock canvass or phone bank in CiviCRM. CiviCRM uses Smart Groups and regular 
Groups as the mechanisms to target specific groups of contacts. Here are a couple of 
examples of how you can use Smart Groups and regular Groups for targeting during your 
campaign: 

• You can use Smart Groups to identify contacts you want to target based on specific 
criteria, such as voter demographics, issue interests, primary language spoken, etc. 

• You can track voter demographics about your contacts using the custom data group 
called Voter Info 

• You can use Groups to identify contacts who subscribe to a particular newsletter or 
issue to do an email blast about your campaign. 

• You can then use these Smart Groups and regular Groups to generate your walk list or 
phone bank list. 

Learn more about working with Smart Groups and regular Groups in the "Tags and Groups" 
chapter of this book. 

Preparing a Campaign Event 

To prepare a campaign event in CiviCRM, there are several setup items you may want to 
consider: 



• Define a specific Campaign Source Code for your event. This Campaign Source Code will 
be used for the event and the activity which holds the individual responses gathered 
during the door knock canvass or phone bank campaign. 

• When you set up your event with the Event Type set to "Campaign" you can record 
the questions being asked during the campaign in the Event Campaign Details area. 

• Decide how you want to identify participants in the campaign event. Maybe you only 
want to identify the staff and volunteers who will be involved in conducting the door 
knock canvass or phone bank. Maybe you'll want to add the targeted contacts as 
participants. Activities will be used to record the responses of each individual contacted 
during the campaign as well as the campaign source code related to the campaign, so it 
may not be necessary to add these contacts to the event. In either case, it is 
recommended to also record the Campaign Source Code in the participant's record in 
the Participant Info area. 

• When capturing responses from each individual during the campaign, consider how you 
plan on getting the data back into CiviCRM. If the plan is to enter data one contact at a 
time, which may make sense for phone banking, you will need to record the response in 
the individual's activity record, with the Activity Type of "Door Knock" or "Phone" in 
the Walk List Responses or Call List Responses area. But if you plan on entering 
batches of data at a time, then you will need to plan to import the responses using the 
Import Activities function. 

Working with Voter History 

When using CiviEngage, plan how you will manage voter history and other voter information 
collected during a voter engagement or electoral cycle. Many organizations have access to a 
voter file from which they manage all their voter engagement work outside of CiviCRM. Once 
the voter engagement or electoral campaign is over and voter information is updated with 
who voted and other demographics, organizations most often will only want to keep 
information on the actual contacts they made during the campaign. In this case, only those 
selected records from the voter file and additional voter information, such as responses to 
specific electoral campaign questions, will be imported and maintained in CiviCRM. These voter 
records then become contacts that organizers will continue to engage and target with base- 
building efforts. 

If you wish to collect voter contacts with their demographics, history, and additional 
information, first import voter contacts (with their contact information and demographics) into 
the Voter Info custom group. Then import additional information as Activities, such as 
responses to electoral campaign canvass questions. 

MOBILIZING INDIVIDUALS TO ATTEND AN EVENT 

The Participant Info custom data group that comes with CiviEngage contains fields that hold 
information about prospective event participants, including a history of interactions between 
your organization and prospective participants. Use this information (such as needs for 
childcare or rides) to bring these individuals to your events. Tracking the history of your 
organization's contact with individuals around events such as an annual membership meeting, 
a direct action, or leadership training can help you to understand the effectiveness of your 
outreach methods and determine how committed or engaged an individual is based on if the 
individual actually attends events after multiple contacts. 

This feature is mostly useful for organizers or staff who have a list of individuals they are 
recruiting to attend an event through multiple phone calls or face-to-face meetings. The 
following CiviCRM tasks could be used to mobilize individuals: 
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1. Conduct a basic or advanced search or use Groups and Smart Groups to create a list of 
the contacts you want to mobilize or invite to the event. 

2. From the search results or Group Contacts screen, you can add the list of contacts to 
the event by selecting Add Contacts to Events from the Actions list. To find out more 
about how to add contacts to events, refer to the Managing Participants chapter in the 
Events section in this book. 

3. Once you add the contacts to the event, you can enter participant information or 
responses from multiple interactions in the Participant Info area in a contact's 
participant record. You can either enter information for one participant by editing the 
participant record itself, or you can add information for a list of participants at one time. 
For example, if you plan to call through your list by viewing the participant list from the 
event listing, you could use Batch Update Participants Via Profile and select one of 
the following custom profiles provided by CiviEngage: 

• Update Event Invite Responses - to record responses from multiple contacts with the 
participant. 

• Update Participant Info - to record general information about participants, such as if 
they need childcare or rides to the event. 

TRACKING FUNDERS AND FOUNDATIONS 

You can track information about and due dates for grant proposals, letters of inquiries, and 
reports for funders by adding an activity related to the funder's contact record and choosing 
from the Proposal, Letter of Inquiry, or Report activity types. 

You can also tailor information about an individual funder, such as their funding areas and 
issue interests, using the Funder Info custom group. In order to view the Funder Info tab, you 
will need to use the Individual sub-contact type, Funder, when you create a new contact that 
is identified as a funder. 

You can tailor information about a foundation (organization record), such as their program 
areas for funding, using the Grant Info custom group. 

TRACKING MEDIA CONTACTS 

As part of civic engagement and community organizing work, it can be useful to track 
information about your media contacts in CiviCRM, especially if you want to know which media 
contacts or outlets are interested in your organization's issues, or have written articles about 
your work, or for identifying who to contact when you want to publicize the work the 
organization is undertaking. 

You can tailor information about an individual media contact, such as their media type (e.g., 
TV, Newspaper, Photographer, etc.), issue interests and beat using the Media Info - Ind 
custom group. Use the Individual sub-contact type, Media Contact, when you create a new 
contact for a media contact. You can then view and edit the Media Info - Ind tab. 

You can also tailor information about a media outlet (organization) such as their media type 
(e.g., TV, Newspaper, Magazine, etc.) using the Media Info - Org custom group. As with the 
individual media person, use the Organization sub-contact type, Media Outlet, when you 
create a new contact for a media outlet. You can then view and edit the Media Info - Org 
tab. 

TRACKING ELECTED OFFICIALS 

Identifying and collecting information about your elected officials could be useful for your 
community organizing and civic engagement work. You may want to know who is an elected 
official in a specific district, or who to contact on their staff, such as the scheduler, or 
spokesperson. 
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You can tailor information about an individual elected official, such as their elected position 
(e.g., city council, Senate, etc.) and their role using the Elected Info custom group. Use the 
Individual sub-contact type, Elected Official, when you create a new contact for an elected 
official. You can then view and edit the Elected Info tab. Remember that staffers, schedulers, 
or spokespeople for an elected official can be entered as the Elected Official subtype. 

REPORTING AND ANALYSIS 

There are two reports packaged with CiviEngage: Walk List and Phonebank List. In addition, 
the Activity Report is enhanced to filter custom activity fields such as those associated with 
the custom group Call List Responses and Walk List Responses. 

The Walk List report allows you to view, print, or export an individual's contact information 
and demographics such as Member Type, Sex, Age, Party Registration, Voter history, along 
with response codes and notes where a volunteer can collect responses during a door knock 
canvass. 

The Phonebank List report is similar to the Walk List report except that this report is used 
exclusively during a phonebank and contain response codes pertaining to phone responses. 

The Walk List and Phonebank List reports are used to collect information during a campaign to 
later be imported or batch entered back into CiviCRM. 

The Activity Report is enhanced to allow you to search, view, print, or export for specific 
responses from a door knock canvass or phonebank campaign. Use this report not only to 
analyze the effectiveness of your campaign (e.g., how many people you contacted and 
collected responses from) but also to analyze responses from your constituency around an 
issue, or to determine whether individuals may become more involved with your 
organization. 

Disabling vs. Deleting Custom Data 

If you decide you don't need to use or view particular custom groups, fields, or values, we 
strongly recommend that you disable the group, field, or value rather than delete them. The 
Walk List and Phonebank List reports rely on these fields, so deleting certain custom data 
could potentially "break" the reports. 
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34. SYSTEM CONFIGURATION FOR MASS 
MAILING 

Configuring the email system using CiviMail is a complex task and needs system administrator 
level skills if you want to set up everything properly. 

You will need to be able to change the configuration of your DNS, create email accounts, 
configure a cronjob, read the headers of an email and possibly change the configuration of 
your SMTP server. 

In this chapter, we are assuming you are using a linux server for your CiviCRM. Most of the 
steps are similar with other OS, but you will need to adapt them to your system and tools. It 
will be easier if you have a basic notion of linux shell and are able to run some simple 
commands. 

The configuration described works fine for mailings of a few hundreds to 10,000 emails. If you 
plan sending emails to 100,000 of contacts, you will want to benchmark several options and 
consider a dedicated SMTP server for instance. Such a configuration is outside the perimeter 
of this book. 

In this chapter let's use gmail - email address for CiviMail configuration. The first step is to 
create a mail account on gmail, as you will need an external mailbox to be able to test the 
configuration. 

CONFIGURE OUTBOUND EMAILS 

You might need to set up the outbound email 

Administer -> Configure -> Global settings -> Outbound Email 

• mail(): this is the default option. If it works, keep it 

• SMTP: if you have a dedicated external mail server. The bounce emails generated locally 
are slightly more complete than the ones from mail(), but in practice hasn't any benefit. 
The SMTP server has too many limitations to be used in this case. 

• Sendmail: kept for compatibility reasons. 

• Disable Outbound Email. 

Send a test email to your account on gmail and verify that you receive it. 

If you have an error message, you need to configure a default from email address (used by all 
the technical or automatic emails sent by civicrm). Please read the chapter on CiviMail 
configuration. 

Sorry. A non-recoverable error has occurred. 

The site administrator needs to enter a valid 'FROM Email Address' in Administei 

If you have received, you need to view the source (show original) of the email you received. It 
should contain the following lines: 

Received: from yourmailserver.example.org (xxx.example.org [12.45.120.30]) 

by mx.google.com with ESMTP id e31si451 9230wej . 3 . 20 10 . 4 . 2 6 . 00 . 38 . 1 6 ; 
Mon, 26 Apr 2010 00:38:17 -0700 (PDT) 

Received-SPF : pass (google.com: best guess record for domain of youremail@examp] 
as permitted sender) client-ip=12 . 45 . 120 . 30 
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• the "Received: from" should correspond to your mail server and be properly configured. 
It might contain information about your hosting provider instead of your domain name. 
This is not a problem as long as the mail server is properly configured, but if you have a 
dedicated IP address for your server, you should try to configure properly the reverse 
DNS so it represent your organisation instead of the default name 

• the "Received-SPF" should be pass or neutral, cf. the chapter below on Sender Policy 
Framework 

Check with your hosting provider if they put a limit on the number of emails you can send or 
if PHP runs in safe mode. In our experience, sending mass mailing is resource intensive, you 
won't have a satisfying experience with a "budget hosting" and the time you will spend 
troubleshooting will cost you much more than upgrading your hosting to a more professional 
one, adapted to the usage you plan. 

Some of your recipients' server are using blacklisting services (DNSBL). They keep a blacklist 
of IP addresses, any mail from which would be prevented from reaching its intended 
destination. If your server is blacklisted (for instance because enough of your recipients flagged 
your emails as spam, or because another website on your server has been flagged as spam), 
you will need to contact the organism that have blacklisted you and try to convince them to 
unlist you. 

They are several websites that helps you testing if you are in a DNSBL. Search for "blacklisting 
email" will give you some. That's something to test on a regular basis. 

CONFIGURE SENDER POLICY FRAMEWORK (SPF) 

By default, SMTP allows any mail server to send any email claiming to be from anyone. It is 
easy for spammers to forge addresses and send spam using your email address (or any 
address). SPF allows you to create a special DNS record listing the IP addresses of the mail 
servers that can legitimately send emails @yourdomain.org. 

If your domain name has already a SPF record, be sure it includes the IP address of your 
CiviCRM server (the one that sends emails, it might be a different one than the one used for 
the web server). 

If you don't have one, consider adding it (you will need to put at least your mail server and 
CiviCRM mail server if they are different). It will increase your chances of having your mass 
mailings end up in the inbox instead of the spam folder, as most mail servers consider that 
receiving an email from a domain name that has a SPF is less likely to be spam if it comes 
from a designated server. 

You can read more about SPF on this site: http://www.openspf.org/lntroduction 

CONFIGURE THE RETURN CHANNEL TO MANAGE 
BOUNCES 

You need to set up a mailbox that will receive the bounced emails. This is an "invisible" email 
address that is only visible at the technical level (the envelope address), but not for the 
recipients. You can name it anyway you want, but in this book, we choose return so the email 
you will need to set up on your mail server for example.org is return@example.org. 

Verify that your account is properly set up by sending a test email from gmail to the mail 
account return(Sexa mple.org you just created. You don't need to be able to read it after the 
set up, but for this configuration phase, you will find it much easier so you can test and verify 
that it receives emails. 
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The principle used to manage bounce is that for each email sent, a new unique "invisible" 
sender address will be created (Variable envelope return paths). Hence, when it receives a 
bounce for one of these unique address, it knows who is the recipient that bounced. You can 
read more about VERP on http://cr.yp.to/proto/verp.txt 

They are two ways of having a "bounce" mailbox that can receive emails for all the VERPs 
addresses: 

Sub-addressing 

Your mail service might allow you to append a "+tag" or "-tag" qualifier to your e-mail 
address (e.g., youremail+tag@example.org). Try to send yourself an email in adding a +tag or - 
tag. 

Several mail servers, like gmail, yahoo and postfix provides this sub-addressing by default. 

If you have received received the mail you sent with a tag, it means that you can directly use 
the mailbox you created ret urnOexam pie. org) "> (ret urn@example.org) to handler the VERP. 

Catch all 

If the sub-addressing doesn't work on your mail server, you will need to define that the mail 
account you created (ret urnOexa mple.org) is the "catch-all" account, ie. Every mail sent to an 
address that isn't a real mail account of one of your staff will end up there, including all the 
bounced emails to the VERP addresses. 

If neither of these methods works, you might want to create an account on gmail and uses it 
specifically to manage the bounces. You will have to set filters in this account so it doesn't 
discard as spam all the bounced emails it will receive. 

Adding the account on CiviMail 

You need to set up this address in Administer -> CiviMail -> Mail accounts as the default email. 

• The mail server, Username, Password are those you created for your mailbox. 

• If your mail server supports it, use IMAP and SLL, otherwise POP. 

• You can leave the return path empty 

• The email domain is the one for your email address (example.org) 

• and the local part is the account you created with '+' appended , eg. "return+" 

Once this mailbox is configured, you will need to configure CiviMail to empty it and identify the 
bounced contacts. The process is bin/EmailProcessor.php 

The easiest is to directly access the page to process the emails on your server for the test 
before properly setting up the tools to process the bounced emails on a regular basis. 

http://example.org/ sites/all/modules/civicrm/bin/EmailProcessor.php? 
name=username&pass=password&key=yoursiteinstallkey 

Read the chapter below on the Cronjob for the details of these parameters. 

If CiviCRM can't properly connect to the mailbox, it displays an error message: 

ezcMailTransportException: An error occured while sending or receiving mail. 

And some extra information about the precise problem, like: 

• Failed to connect to the server 
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• The P0P3 server did not accept the password: -ERR [AUTH] Username and password not accepted 

• The 1MAP server did not accept the password: -ERR [AUTH] Username and password not accepted 



Once you have verified that CiviCRM can handle properly the return channel, you can set it up 
to automatically process the replies and bounces on a regular basis. 

SENDING OF MASS MAILING 

Mass mailings are generated via the web interface, but then queued to be send by a 
background process that periodically checks if they are any mailing waiting to be processed 
(cronjob): bin/civimail.cronjob.php 

Read the chapter below on how to run it on a regular basis 



CRONJOB: TASK SCHEDULER 

For both processing the emails to send and the bounced emails to be processed, you will need 
to run a process several time an hour. On linux, this is done by configuring a cronjob. 

They need to run using a drupal or ! Joomla! account. Create one specifically for this task (eg: 
mailprocess), and give it a long password {eg:seol-lzprm42amv-psyc) and grant it access on 
CiviCRM and CiviMail. Do not change the account password without changing the password in 
the configuration files of this cronjob. 

Read the cron documentation and adapt based on your need, but for instance to run this 
every five minutes, on your server command line type 

crontab -e 

and then enter the following line: 



*/5 * * * * command_to_run 

Each of the processes has two modes: to be run from the shell using php-cli, or by relying on 
the webserver and loading a special page. 

The cronjob should be set up so that mail is sent periodicly. If you need the email to be sent 
right away you could trigger the sending process by visiting the 

http://example,org/civicrm/mailing/queue&reset=1 URL. Please note that you should use this 
sparingly. It could utilize A LOT of server resources and cause your database to slow down 
noticeably. The administrative settings for sending email are usually configured to minimize the 
load on the server and is a more efficient way of sending your mass email. 

From the shell: php-cli 

From the shell, type php -v 

PHP 5.2.3-lubuntu6.5 (cli) (built: Feb 11 2009 19:55:53) 

Copyright (c) 1997-2007 The PHP Group 

Zend Engine v2 . 2 . , Copyright (c) 1998-2007 Zend Technologies 

with eAccelerator vO.9.5.3, Copyright (c) 2004-2006 eAccelerator , by eAccele 

If you have a (cli) in the message, you have php-cli installed and you should use this option, as 
it has several advantages: 
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• you can run this background script in a lower priority than your web server, so even if it 
takes a lot of CPU, it won't interfere with the regular users of your site. 

• you can set different memory limits for the php-cli and the php used by your web 
server 

• you avoid the overhead of the webserver and the http layer 

• you don't have any problem of timeout 

So the complete configuration is : 

# This must be set to the directory where civicrm is installed. 
CIVI_ROOT=/var/www/civicrm 

USER-www- data 
MAILTO-"you@example . org" 

# Location of the PHP Command Line Interface binary, nice -19 forces to run at c 
PHP-nice -nl9 /usr/bin/php 

#line to be modified according to the informations below 
PARAMS- -sdefault -umailprocess -pseol-lzprm42amv-psyc 
#cronjob send 

# m h dom mon dow command 

*/5 * * * * cd $CIVI_ROOT,-$PHP bin/ciuimail.cronjob.php $PARAMS 
*/5 * * * * cd $CIVI_ROOT;$PHP bin/EmailProcessor . php $PARAMS 

The user that run the scripts (www-data) needs to be able to write in the temporary folder. 
Depending on your configuration, it might be a different user than www-data. 

PARAMS contains: 

1. user login (-umailprocess) 

2. password (-pseol-lzprm42amv-psyc) you have defined 

3. the site you used (-sdefault) in general on drupal, -sexample.org if you are multi-sites 

From the web server 

You can access the two processes from pages on your web server too. 

wget -0 - -q -t 1 --post-data- ' name-mailprocess &pass-seol-lzprm42amv-psyc&key-^ 
wget -0 - -q -t 1 --post-data- ' name=mailprocess&pass-seol-lzprm42amv-psyc&key-^ 

You need to add an extra parameter key, that is defined in your civicrm. settings. php read the 
chapter on the REST interface for more information about this parameter. 
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CONFIGURATION 

You will need to configure both Drupal and CiviEngage to use the module. 

CONFIGURING CIVICRM FOR CIVIENGAGE 

CiviEngage can be configured using the following CiviCRM core features: 
Custom Data Groups 

Configure custom data groups and fields to track voter demographics, issue interests, 
leadership levels, volunteer interests, and information about funders, media contacts, and 
elected officials. 

Contact Subtypes 

CiviEngage takes advantage of CiviCRM contact subtypes to expose custom data groups 
associated only with specific subtypes. The following are new contact subtypes: 

Individual subtypes: 

• Media Contact - will expose a contact tab containing information specific to media 
contacts, such as their media type (e.g. Newspaper, Radio, TV, etc.), their "Beat," and 
the media issue interests 

• Elected Official - will expose a contact tab containing information specific to elected 
officials, such as their elected level (e.g. City Council, Senate, etc.) and the role (e.g. 
scheduler, spokesperson, etc.) 

• Funder - will expose a contact tab containing information specific to funders, such as 
their program areas and their issue interests. 

Organization subtypes: 

• Media Outlet - will expose a contact tab containing information about their type of 
media, such as TV, Radio, Wire, Newspaper, Magazine, etc. 

Campaign Source Codes 

CiviEngage uses Campaign Source Codes that you can tailor to describe and track related 
activities, events, event participants, contributions, or memberships. Campaign Source Codes 
can be used to describe a group of related activities, events, contributions, or memberships 
for a specific campaign, project, or program. 

Note: A "Campaign" does not necessarily mean a formal campaign, but can also generally be 
defined as a specific project, program, or organizing activity. 

Door Knock Canvass and Phone Bank Tracking 

• Events used for Door Knock Canvass or Phone Bank - Use the Campaign Event Type to 
expose Event custom fields that allows you to store up to four specific questions being 
asked during a door knock canvass or phone bank. 

• Activities used to Collect Responses from Door Knock Canvass or Phone Bank 
Campaigns - Use the Door Knock and Phone Call Activity Types to expose custom 
fields where you can collect an individual's responses during a door knock canvass or 
phone bank. 

Reports 
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• Walk List Report - view, print or export certain demographic and other constituent 
information in a specific geographic area to collect responses to be used during a door 
knock canvass. The Walk List Report takes advantage of the optional address parsing 
feature to build the report. 

• Call List Report - view, print or export certain demographic and other constituent 
information along with an area to collect responses to be used during a phone bank. 

• Activity Report - includes filters for activity custom fields so that you can build a report 
of specific activities based on criteria about your constituency, such as creating a report 
to analyze particular responses from a door knock canvass or phone bank. 

Grant Proposal and Report Tracking 

CiviEngage uses the Proposal, Letter of Inquiry and Report Activity Types to expose custom 
fields to track information and schedules for proposals, letters of inquiries and reports related 
to an individual funder or foundation. 

Custom Profiles 

CiviEngage configures several custom profiles for easier batch updating of individual or 
organization information, such as voter demographics, issue interests, volunteer interests, or 
event participant information. To learn more about profiles, please refer to the "Profiles" 
section of the book. 

CONFIGURING CIVIENGAGE 

When you install CiviEngage a number of custom fields are automatically created. These fields 
are designed to support your community organizing work. Most of these fields are multiple 
choice fields which have been pre-populated with sample options. Before you start using 
CiviEngage, you need to review and modify the supplied options to meet your needs. 

Begin by going to Administer -> Customize -> Custom Data in the navigation menu. In the 
following list bolded items are Group Header entries in the Custom Data screen. The bulleted 
items are custom fields under those Group Headers that have been added by CiviEngage; the 
other fields under these group headers are standard to CiviCRM. The choices for these custom 
fields should be edited before you use CiviEngage. You should add, delete, or edit the available 
options for each custom field to make them better fit your organization's needs. 

Communications Details 

• Best Time to Contact 

Voter Info 

All of the fields in this custom data group are added by CiviEngage, so you should review and 
edit them all to suit your needs. You may also want to add specific local voter fields that apply 
to you. 

Constituent Info - Individuals 

• Constituent Type 

• Staff Responsible - note that the values for this field are also used for Event Contact 
Person. Replace the sample names in the list with your staff, member or volunteer 
coordinators, and other folks that have individuals assigned to them. 

• How Started - edit this list to fit the ways in which members are brought into your 
organization. 

Grassroots Info 
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• Member Status - three status choices included by default. Think about other member 
statuses that might work for your organization and add or remove as needed. 

• Leadership Level - The default options for tracking an individual's leadership level within 
your organization are 1-5. Change this to match however your organization tracks this 
information. 

• Issue Interest - this custom field uses the same set of options as the Funding Areas and 
Funder Issue Interest fields. It is a list of issues that your organization works on or 
tracks. 

• Volunteer Interests - a list of volunteer activities that your members can take on. 

Constituent Info - Organizations 

• Constituent Type - Org 
Grant Info 

• Funding Areas - this custom field uses the same set of options for Issue Interest and 
Funder Issue Interest. 

Participant Info 

• Participant Campaign Code - this custom field uses the same set of options as the 
Contribution Campaign Code, Event Campaign Code, Activity Campaign Code and 
Membership Source Code fields. Delete the example campaigns and add your own. This 
is the mechanism CiviEngage uses to connect a contact's participation across all these 
different actions. For example, a Campaign called "House Party 10-1-2010" could have an 
Event tied to it, a participant of that Event tied to it, an activity when an organizer calls 
a contact inviting them to attend an Event, a membership entry when they become 
members at the Event and a contribution when they pay their dues. 

Contribution Source 

• Contribution Campaign Code - see Participant Campaign Code. 

• Contribution Campaign Method - this custom field uses the same set of options as 
Membership Source Campaign. Add different types of interactions or locations where 
you would be engaging potential members and donors. 

Event Details 

• Event Contact Person - also used for Staff Responsible. Add all appropriate people to 
this list. 

• Event Campaign Code - see Participant Campaign Code. 

Activity Source Details 

• Activity Campaign Code - see Participant Campaign Code. 

Organizational Details 

This custom group is used to store information that is specific to organizations. There is only 
one example currently. 

• Rating - if you need to evaluate organizations in some way, change the options to reflect 
that. 

Demographics 
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• Ethnicity 

• Primary Language - this custom field uses the same set of options as Secondary 
Language. Only one entry can be selected for each contact for this field. 

• Secondary Language - also used for Primary Language, but as many choices as needed 
can be checked. 

Media Info - Org 

This custom group is only applicable to the New Media Outlet contact subtype. 

• Media Type - Org - this custom field uses the same set of options as Media Type - Ind: 
TV, Radio, Wire, Newspaper, Magazine 

Media Info - Ind 

This custom group is only applicable to the New Media Contact contact subtype. 

• Media Type - Ind - this custom field uses the same set of options as Media Type - Org 

• Beat - this refers to the general category of topics that a media contact covers, such as 
local government, education, neighborhoods, religion, labor, etc. 

• Media Issue Interest - uses the same option list as Issue Interest. As you come to know 
a reporter, you will learn the issues they are particularly interested in, even if it differs 
from their assigned beat. 

Elected Info 

This custom group is only applicable to the New Elected Official contact subtype. 

• Elected Level - the governmental body the individual is part of (City Council, state 
legislature, mayor, etc.) 

• Role - Whether the contact is the elected official, or the official's staff, spokesperson, 
etc. 

Funder Info 

This custom group is only applicable to the New Funder contact subtype. 

• Funder Issue Interest - this custom field uses the same set of options as Issue Interest 
and Funding Areas. 

Membership Source Details 

• Membership Source Code - Uses the same codes as the Participant Campaign Code and 
Contribution Campaign Code. 

• Membership Source Campaign - also used for contributions. Add different types of 
interactions or locations where you would be engaging potential members and donors. 
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ESSENTIAL TASKS 

This chapter provides instructions on how to do some of the common tasks associated with 
the CiviEngage module. 

PRINTING A WALK LIST 

CiviEngage offers a report that allows you to easily print walk lists for folks who are doing 
canvassing, Get Out the Vote (GOTV) or other door knocking activities. 

1. If you want to use Groups or Smart Groups to develop your walk list, be sure to create 
the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the walk list report. Choose whether you want the Country or Email field to 
display. 

4. Scroll down to the "Set Filters" section. You must select a filter to obtain results. All 
your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the report results, but if you click on "Print Preview" you will see your walk list. 
You can use your browser's Print Preview feature to see the walk list on a per-page 
basis. 

PRINTING A PHONE LIST 

CiviEngage offers a report that allows you to easily print phone lists for folks who are doing 
phone banks or other mass phoning activities. 

1. If you want to use Groups or Smart Groups to develop your phone list, be sure to 
create the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the phone list report. Choose the columns you want to display from the 
template screen. 

4. Scroll down to the "Set Filters" section. You must select a filter in order to obtain 
results. All your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the results but if you click on "Print Preview" you will see your phone list. You can 
now use your browser's Print Preview feature to see the phone list on a per-page basis. 

CREATE A CAMPAIGN SOURCE CODE 

In order to use CiviEngage effectively, you need to create "campaigns" that you connect all 
your activities to. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Participant Info in the list and click the corresponding "View and Edit Custom Fields" 
link. This gives you a list of Custom Fields. 

3. Find Participant Campaign Code and click the "Edit Multiple Choice Options" link. Now you 
are seeing a list of the interests. 

4. Scroll down and click on "New Option" and add your new campaign. 

Please note that this new campaign code will now be available for Event, Membership and 
Contribution Campaign Codes as well as in the Participant Campaign Code that it was just 
created in. 

ADD AN ISSUE INTEREST 
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To better understand and track the areas that your members and constituencies are 
interested in working on, CiviEngage provides a field that collects this information. Customize 
this list to meet the needs of your particular organization. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Grassroots Info in the list and click on the corresponding "View and Edit Custom 
Fields" link. This gives you a list of Custom Fields. 

3. Find Issue Interest and click the "Edit Multiple Choice Options" link. Now you are seeing a 
list of the interests. 

4. Scroll down and click "New Option" and add your new interest. 

Please note that this new issue will also appear in Funding Areas and Funder Issue Interest as 
well as in the Issue Interest that it was just created in. 

TRACK WALK LIST/CALL LIST RESPONSES 

Responses to the questions your canvassers or phone bankers ask are tracked in an 
individual's activity record. The text of the questions are tracked in the event record. In order 
to properly configure this, start with creating the event. 

1. Click on Events -> New Event. 

2. Choose Campaign for your Event Type, which will let you see the Event Campaign Details 
section. 

3. Scroll down to the Event Campaign Details section and add the text to the questions for 
this particular campaign. 

4. You will also want to add an Event Campaign Code, which is in the Event Details section. 

Next you would go to a contact record to create a "Door Knock" or "Phone Call" activity and 
finish configuring this functionality. 

1. Go to a contact's record and click on "new activity." 

2. Choose "Phone Call" or "Door Knock" and you will get the Activities screen. 

3. Scroll down and click on the Call List Responses section. 

4. Now you can record the responses. 

5. You then add the Activity Campaign Code in the Activity Source Details section. Make 
sure you choose the same campaign as you did for the Event. 
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PRINT AN ACTIVITY REPORT 

One of the features of CiviEngage is the ability to track the different activities that your 
members are engaged in. Use the activity report to better understand what your members 
are doing. 
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1. Click on Reports -> Create Reports from Template . 

2. Choose the Activity Report. This brings up the Activity Report Template. You are now 
looking at all the options available for printing a report based on the activities CiviEngage 
offers that your contacts are engaged in. 

3. The first section lists the columns that are available for your report. Use the check 
boxes to decide what information you want your report to show. The default values are 
Assignee Contact Name , Target Contact Name , Activity Type , Subject, Activity Date and 
Activity Status . You can choose columns from Walk List Responses, Leadership Level 
(from Activities), Call List Responses, Proposal Info or Activity Source Details. 

If, for example, you want a report of Walk List Responses from a specific campaign, you 
would check boxes from the Walk List Responses section and choose the Activity 
Campaign Code from the Activity Source Details section. Please note that the default 
value for Activity Date is "this month." If you want a different range of dates you have 
many options. Click on "this month" and you will see all the options available. Included is 
Date Range, where you can choose a specific range of dates. 

4. The next section allows you to group your data by the Source Contact (the default 
value), Activity Date or Activity Type . Check the appropriate box for your report. 

5. The final section is for filtering your data. Here you can choose data from any of the 
activity fields that CiviEngage offers. 

To continue our example, you might choose to include data where the first two Walk 
List questions were answered yes. Choose Y in the appropriate boxes and scroll down to 
the Activity Source Detail section and choose the appropriate Activity Campaign Code . 
Click Preview Report and view your results. 

6. Once you have your results, you have a number of options. You can "Preview" the 
report, "Preview" the PDF of the report, "Preview" the CSV (export your report into a 
spreadsheet), or "Add the contacts to a group." 

SEARCH FOR ACTIVITIES 

The are a number of ways to search for the activities that you create using CiviEngage: 

• Run a report, as explained above 

• Use the Find Activities search option 

• Use the CiviCRM Advanced Search 

• Run an Activity Search, which is in Custom Searches. 

Using the Find Activities search option 

1. Click on Search -> Find Activities . 

2. You are presented with a number of search criteria options. You can enter the name or 
email address of a contact in the database. You can choose one or more activity types. 
You can add a range of dates during which activities happened. You can search for 
contacts in specific Activity Roles: With, Created By and Assigned to. You can look for 
specific subjects, test activities or by the status of the activity. Each criterion you select 
will narrow your search results. 

3. Click Search and you will get to the Search Results screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using Advanced Search to find Activities 
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1. Click on Search -> Find Contacts - Advanced Search . 

2. Scroll down to the Activities section and click on it. Here you find all the options available 
in CiviEngage for activities. 

3. Once you choose your search options and click Search you will get to the Search Results 
screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using the Custom Search: Activity Search 

1. Click on Search -> Custom Searches... -> Activity Search . 

2. You are presented with different criteria by which you can search for information. Enter 
your search terms and click Search. 

3. The Search Results provides the Name of the person, the Status, Type and Subject of 
the Activity and who assigned the activity. You also have a button for viewing and 
editing each activity record. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 
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37. 



WHAT IS CIVICASE? 



CiviCase is a way to track and manage a sequence of interactions between people in your 
organisation and contacts in CiviCRM. In addition to tracking and managing your organisation's 
interactions with clients or constituents, CiviCase can also manage internal organisational 
interactions. 

CiviCase tracks interactions in two ways: as cases and as activities. 

Activities are single interactions. For example, if a constituent calls to request information and 
the staff person directs them to a website, it would be recorded as an activity, with a brief 
description of how the staff person followed-up. CiviCRM will auto-generate some activities in 
conjunction with other actions, such as logging an email receipt for event registrations. 

Cases are used to track more complex interactions or communication processes. Multiple 
activities can be grouped together into one case, and these activities can be optionally 
structured in a timeline. A case can be used to track a specific workflow that must be 
followed, for example: a client fills out an intake form, then has an initial meeting with a staff 
person, and finally receives a certificate from the organisation for meeting certain goals. 

As well as linking activities around a common case, CiviCase identifies the people involved and 
their role(s) in the case. For example, a website project would be a case, with tasks such as 
design, develop and write content being activities within that case, and the people involved 
would have roles as designer, developer, tester, writer, etc. 

ACTUAL SCENARIOS 

Organisations have employed CiviCase in a wide variety of situations. Here are a few 
examples of different types of organisations and how they might employ CiviCase. 

Managing Legislator-Constituent Interactions 

A Legislator's staff may manage hundreds of interactions with constituents and communities 
daily. CiviCase provides a flexible and predictable way of allowing Legislative staff to manage 
and track these interactions while avoiding duplication (for example, if a constituent calls in 
about a topic that a staffer is already working on). CiviCase also automates the task of 
remembering and scheduling follow up activities by presenting staffers with a list of upcoming 
case activities that require their attention. 

Below are some scenarios in which CiviCase can be used to effectively record interactions 
between Legislative staff and constituents: 

• The Legislator's office receives a phone call from a constituent requesting agency 
support. A staffer logs the call as a CiviCase activity and then sets up a follow up call in 
the next week to make sure that action has been taken on the agency's behalf. 

• A Legislative staffer records where and when a Legislator staff heard from a constituent 
about a government service problem. 

• The Legislator's staff records event invitations that a Legislator's scheduler must 
respond to. 

• A Legislative staffer receives a phone call about illegal dumping near the caller's home. 
The staffer creates a case recording the location of the reported issue and assigns the 
task of following up with the Health Department to another member of the Legislator's 
staff. When the staff member logs in to CiviCRM they see that a new case activity has 
been assigned to them. The Staffer then contacts the Health Department on behalf of 
the constituent and mails the constituent to confirm that the Health Department has 
been informed of the situation. 
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Helping clients with emotional health or substance abuse problems 

Social services agencies have specific workflows for processing clients through the variety of 
services that they provide. CiviCase can be used to outline and record the path that clients 
travel on their way to recovery. 

When a client phones a social services agency, they will speak to an intake counsellor. The 
intake counsellor can set up a case to quickly record and determine what the clients' needs 
are, who are the people that need to be involved, and then set up a follow up meeting with a 
social worker. 
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PLANNING WITH CIVIENGAGE 

CiviEngage packages a set of custom data groups and fields, reports, and other features for 
use in civic engagement and community organizing work. This chapter will describe the general 
concepts and planning needed to use CiviEngage effectively. 

WHAT YOU NEED TO KNOW 

The following are concepts, custom fields and values to keep in mind when preparing to use 
CiviEngage. 

Campaign Source Code 

Campaign Source Codes are descriptive values used to identify related activities, events, 
contributions, and memberships and map how these activities and transactions are linked 
together. Campaign Source Codes are also useful for identifying these sets of activities or 
transactions as part of a larger campaign, project, or program. 

For example, an organization is conducting a door knock canvass around a particular issue 
during a specific range of dates. The organization may want to use campaign source codes to 
link together the activities (where responses to door knock canvass questions are captured), 
the event (the door knock canvass campaign itself), and any contributions made during the 
canvass to be able to analyze the effectiveness of the campaign. 

Activity, Event, Contribution, Participant, and Membership records each contain a custom field 
to store a Campaign Source Code, that all share a common option list where Campaign Source 
Code values can be added and edited. 

Your organization can establish a standard method for creating new Campaign Source Codes 
so that the codes are consistent and easy to sort and understand at a glance. For example, 
you can specify that annual campaigns always include the year at the either the beginning or 
the end of the Campaign Source Code, not both, so that you don't wind up with "2009 Annual 
Campaign" and "Annual Campaign 2010." 

Issue Interests 

Issue Interests are issues that your organization works on or tracks. They are included in 
CiviEngage as a single option list shared across multiple contexts: 

• Grassroots Info: Issue Interests for individuals 

• Media Issue Interests for media contacts 

• Funder Issue Interests for funders 

• Grant Info: Funding Areas for organizations 

It is important to remember that despite appearing with different labels in these different 
contexts, you are still dealing with just one shared list of options. 

In planning to use CiviEngage you should come up with a list of distinct issues that are 
important to your organization and that you will want to utilize when tracking individuals' 
interest in your organization's work, the issues that your media contacts may be interested in 
covering, funders' general interests and the specific areas of work included in particular grants. 

Volunteer Interest 
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Volunteer interests are activities that your organization's volunteers can take on and 
participate in; you can indicate each individual's interest in participating in these ways. They 
are included in CiviEngage as an option list. In planning to use CiviEngage you should establish a 
list of your organization's current volunteer activities as well as any activities that you are 
planning to launch in the future. Some examples of volunteer interests are canvassing, phone 
banking, and tabling. 

Cleaning your Address Data 

Cleaning your address data means standardizing addresses to conform to the conventions 
defined by the United States Postal Service's Standards for Addresses. Standardizing how 
addresses are entered into CiviCRM will allow for more accurate search results when searching 
by address and is essential to generate accurate Walk List reports. CiviCRM will parse 
addresses based on the USPS standards. To find out more about how Address Parsing is 
handled and used in CiviCRM, refer to the Address Parsing chapter of this book. When adding 
or editing contacts you will be entering or editing address elements including street number, 
street name, and Apt/Unit/Suite number according to these standards. 

When planning to import pre-existing data into CiviCRM for use in CiviEngage it is essential that 
you plan to clean up address data before importing. 

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 
at http://pe.usps.com/text/pub28/welcome.htm . 

TRACKING CIVIC ENGAGEMENT AND CAMPAIGNS 

CiviEngage is designed to manage interactions with constituents around an organization's civic 
engagement and base-building work, such as door knock canvassing and phone banking. There 
are several concepts and details to consider when preparing for these types of campaigns. 

Working with Your Universe of Contacts 

In preparing for your campaign, you will need to identify the audiences you will be targeting for 
your door knock canvass or phone bank in CiviCRM. CiviCRM uses Smart Groups and regular 
Groups as the mechanisms to target specific groups of contacts. Here are a couple of 
examples of how you can use Smart Groups and regular Groups for targeting during your 
campaign: 

• You can use Smart Groups to identify contacts you want to target based on specific 
criteria, such as voter demographics, issue interests, primary language spoken, etc. 

• You can track voter demographics about your contacts using the custom data group 
called Voter Info 

• You can use Groups to identify contacts who subscribe to a particular newsletter or 
issue to do an email blast about your campaign. 

• You can then use these Smart Groups and regular Groups to generate your walk list or 
phone bank list. 

Learn more about working with Smart Groups and regular Groups in the "Tags and Groups" 
chapter of this book. 

Preparing a Campaign Event 

To prepare a campaign event in CiviCRM, there are several setup items you may want to 
consider: 
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• Define a specific Campaign Source Code for your event. This Campaign Source Code will 
be used for the event and the activity which holds the individual responses gathered 
during the door knock canvass or phone bank campaign. 

• When you set up your event with the Event Type set to "Campaign" you can record 
the questions being asked during the campaign in the Event Campaign Details area. 

• Decide how you want to identify participants in the campaign event. Maybe you only 
want to identify the staff and volunteers who will be involved in conducting the door 
knock canvass or phone bank. Maybe you'll want to add the targeted contacts as 
participants. Activities will be used to record the responses of each individual contacted 
during the campaign as well as the campaign source code related to the campaign, so it 
may not be necessary to add these contacts to the event. In either case, it is 
recommended to also record the Campaign Source Code in the participant's record in 
the Participant Info area. 

• When capturing responses from each individual during the campaign, consider how you 
plan on getting the data back into CiviCRM. If the plan is to enter data one contact at a 
time, which may make sense for phone banking, you will need to record the response in 
the individual's activity record, with the Activity Type of "Door Knock" or "Phone" in 
the Walk List Responses or Call List Responses area. But if you plan on entering 
batches of data at a time, then you will need to plan to import the responses using the 
Import Activities function. 

Working with Voter History 

When using CiviEngage, plan how you will manage voter history and other voter information 
collected during a voter engagement or electoral cycle. Many organizations have access to a 
voter file from which they manage all their voter engagement work outside of CiviCRM. Once 
the voter engagement or electoral campaign is over and voter information is updated with 
who voted and other demographics, organizations most often will only want to keep 
information on the actual contacts they made during the campaign. In this case, only those 
selected records from the voter file and additional voter information, such as responses to 
specific electoral campaign questions, will be imported and maintained in CiviCRM. These voter 
records then become contacts that organizers will continue to engage and target with base- 
building efforts. 

If you wish to collect voter contacts with their demographics, history, and additional 
information, first import voter contacts (with their contact information and demographics) into 
the Voter Info custom group. Then import additional information as Activities, such as 
responses to electoral campaign canvass questions. 

MOBILIZING INDIVIDUALS TO ATTEND AN EVENT 

The Participant Info custom data group that comes with CiviEngage contains fields that hold 
information about prospective event participants, including a history of interactions between 
your organization and prospective participants. Use this information (such as needs for 
childcare or rides) to bring these individuals to your events. Tracking the history of your 
organization's contact with individuals around events such as an annual membership meeting, 
a direct action, or leadership training can help you to understand the effectiveness of your 
outreach methods and determine how committed or engaged an individual is based on if the 
individual actually attends events after multiple contacts. 

This feature is mostly useful for organizers or staff who have a list of individuals they are 
recruiting to attend an event through multiple phone calls or face-to-face meetings. The 
following CiviCRM tasks could be used to mobilize individuals: 
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1. Conduct a basic or advanced search or use Groups and Smart Groups to create a list of 
the contacts you want to mobilize or invite to the event. 

2. From the search results or Group Contacts screen, you can add the list of contacts to 
the event by selecting Add Contacts to Events from the Actions list. To find out more 
about how to add contacts to events, refer to the Managing Participants chapter in the 
Events section in this book. 

3. Once you add the contacts to the event, you can enter participant information or 
responses from multiple interactions in the Participant Info area in a contact's 
participant record. You can either enter information for one participant by editing the 
participant record itself, or you can add information for a list of participants at one time. 
For example, if you plan to call through your list by viewing the participant list from the 
event listing, you could use Batch Update Participants Via Profile and select one of 
the following custom profiles provided by CiviEngage: 

• Update Event Invite Responses - to record responses from multiple contacts with the 
participant. 

• Update Participant Info - to record general information about participants, such as if 
they need childcare or rides to the event. 

TRACKING FUNDERS AND FOUNDATIONS 

You can track information about and due dates for grant proposals, letters of inquiries, and 
reports for funders by adding an activity related to the funder's contact record and choosing 
from the Proposal, Letter of Inquiry, or Report activity types. 

You can also tailor information about an individual funder, such as their funding areas and 
issue interests, using the Funder Info custom group. In order to view the Funder Info tab, you 
will need to use the Individual sub-contact type, Funder, when you create a new contact that 
is identified as a funder. 

You can tailor information about a foundation (organization record), such as their program 
areas for funding, using the Grant Info custom group. 

TRACKING MEDIA CONTACTS 

As part of civic engagement and community organizing work, it can be useful to track 
information about your media contacts in CiviCRM, especially if you want to know which media 
contacts or outlets are interested in your organization's issues, or have written articles about 
your work, or for identifying who to contact when you want to publicize the work the 
organization is undertaking. 

You can tailor information about an individual media contact, such as their media type (e.g., 
TV, Newspaper, Photographer, etc.), issue interests and beat using the Media Info - Ind 
custom group. Use the Individual sub-contact type, Media Contact, when you create a new 
contact for a media contact. You can then view and edit the Media Info - Ind tab. 

You can also tailor information about a media outlet (organization) such as their media type 
(e.g., TV, Newspaper, Magazine, etc.) using the Media Info - Org custom group. As with the 
individual media person, use the Organization sub-contact type, Media Outlet, when you 
create a new contact for a media outlet. You can then view and edit the Media Info - Org 
tab. 

TRACKING ELECTED OFFICIALS 

Identifying and collecting information about your elected officials could be useful for your 
community organizing and civic engagement work. You may want to know who is an elected 
official in a specific district, or who to contact on their staff, such as the scheduler, or 
spokesperson. 
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You can tailor information about an individual elected official, such as their elected position 
(e.g., city council, Senate, etc.) and their role using the Elected Info custom group. Use the 
Individual sub-contact type, Elected Official, when you create a new contact for an elected 
official. You can then view and edit the Elected Info tab. Remember that staffers, schedulers, 
or spokespeople for an elected official can be entered as the Elected Official subtype. 

REPORTING AND ANALYSIS 

There are two reports packaged with CiviEngage: Walk List and Phonebank List. In addition, 
the Activity Report is enhanced to filter custom activity fields such as those associated with 
the custom group Call List Responses and Walk List Responses. 

The Walk List report allows you to view, print, or export an individual's contact information 
and demographics such as Member Type, Sex, Age, Party Registration, Voter history, along 
with response codes and notes where a volunteer can collect responses during a door knock 
canvass. 

The Phonebank List report is similar to the Walk List report except that this report is used 
exclusively during a phonebank and contain response codes pertaining to phone responses. 

The Walk List and Phonebank List reports are used to collect information during a campaign to 
later be imported or batch entered back into CiviCRM. 

The Activity Report is enhanced to allow you to search, view, print, or export for specific 
responses from a door knock canvass or phonebank campaign. Use this report not only to 
analyze the effectiveness of your campaign (e.g., how many people you contacted and 
collected responses from) but also to analyze responses from your constituency around an 
issue, or to determine whether individuals may become more involved with your 
organization. 

Disabling vs. Deleting Custom Data 

If you decide you don't need to use or view particular custom groups, fields, or values, we 
strongly recommend that you disable the group, field, or value rather than delete them. The 
Walk List and Phonebank List reports rely on these fields, so deleting certain custom data 
could potentially "break" the reports. 
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CONFIGURATION 

You will need to configure both Drupal and CiviEngage to use the module. 

CONFIGURING CIVICRM FOR CIVIENGAGE 

CiviEngage can be configured using the following CiviCRM core features: 
Custom Data Groups 

Configure custom data groups and fields to track voter demographics, issue interests, 
leadership levels, volunteer interests, and information about funders, media contacts, and 
elected officials. 

Contact Subtypes 

CiviEngage takes advantage of CiviCRM contact subtypes to expose custom data groups 
associated only with specific subtypes. The following are new contact subtypes: 

Individual subtypes: 

• Media Contact - will expose a contact tab containing information specific to media 
contacts, such as their media type (e.g. Newspaper, Radio, TV, etc.), their "Beat," and 
the media issue interests 

• Elected Official - will expose a contact tab containing information specific to elected 
officials, such as their elected level (e.g. City Council, Senate, etc.) and the role (e.g. 
scheduler, spokesperson, etc.) 

• Funder - will expose a contact tab containing information specific to funders, such as 
their program areas and their issue interests. 

Organization subtypes: 

• Media Outlet - will expose a contact tab containing information about their type of 
media, such as TV, Radio, Wire, Newspaper, Magazine, etc. 

Campaign Source Codes 

CiviEngage uses Campaign Source Codes that you can tailor to describe and track related 
activities, events, event participants, contributions, or memberships. Campaign Source Codes 
can be used to describe a group of related activities, events, contributions, or memberships 
for a specific campaign, project, or program. 

Note: A "Campaign" does not necessarily mean a formal campaign, but can also generally be 
defined as a specific project, program, or organizing activity. 

Door Knock Canvass and Phone Bank Tracking 

• Events used for Door Knock Canvass or Phone Bank - Use the Campaign Event Type to 
expose Event custom fields that allows you to store up to four specific questions being 
asked during a door knock canvass or phone bank. 

• Activities used to Collect Responses from Door Knock Canvass or Phone Bank 
Campaigns - Use the Door Knock and Phone Call Activity Types to expose custom 
fields where you can collect an individual's responses during a door knock canvass or 
phone bank. 

Reports 
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• Walk List Report - view, print or export certain demographic and other constituent 
information in a specific geographic area to collect responses to be used during a door 
knock canvass. The Walk List Report takes advantage of the optional address parsing 
feature to build the report. 

• Call List Report - view, print or export certain demographic and other constituent 
information along with an area to collect responses to be used during a phone bank. 

• Activity Report - includes filters for activity custom fields so that you can build a report 
of specific activities based on criteria about your constituency, such as creating a report 
to analyze particular responses from a door knock canvass or phone bank. 

Grant Proposal and Report Tracking 

CiviEngage uses the Proposal, Letter of Inquiry and Report Activity Types to expose custom 
fields to track information and schedules for proposals, letters of inquiries and reports related 
to an individual funder or foundation. 

Custom Profiles 

CiviEngage configures several custom profiles for easier batch updating of individual or 
organization information, such as voter demographics, issue interests, volunteer interests, or 
event participant information. To learn more about profiles, please refer to the "Profiles" 
section of the book. 

CONFIGURING CIVIENGAGE 

When you install CiviEngage a number of custom fields are automatically created. These fields 
are designed to support your community organizing work. Most of these fields are multiple 
choice fields which have been pre-populated with sample options. Before you start using 
CiviEngage, you need to review and modify the supplied options to meet your needs. 

Begin by going to Administer -> Customize -> Custom Data in the navigation menu. In the 
following list bolded items are Group Header entries in the Custom Data screen. The bulleted 
items are custom fields under those Group Headers that have been added by CiviEngage; the 
other fields under these group headers are standard to CiviCRM. The choices for these custom 
fields should be edited before you use CiviEngage. You should add, delete, or edit the available 
options for each custom field to make them better fit your organization's needs. 

Communications Details 

• Best Time to Contact 

Voter Info 

All of the fields in this custom data group are added by CiviEngage, so you should review and 
edit them all to suit your needs. You may also want to add specific local voter fields that apply 
to you. 

Constituent Info - Individuals 

• Constituent Type 

• Staff Responsible - note that the values for this field are also used for Event Contact 
Person. Replace the sample names in the list with your staff, member or volunteer 
coordinators, and other folks that have individuals assigned to them. 

• How Started - edit this list to fit the ways in which members are brought into your 
organization. 

Grassroots Info 
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• Member Status - three status choices included by default. Think about other member 
statuses that might work for your organization and add or remove as needed. 

• Leadership Level - The default options for tracking an individual's leadership level within 
your organization are 1-5. Change this to match however your organization tracks this 
information. 

• Issue Interest - this custom field uses the same set of options as the Funding Areas and 
Funder Issue Interest fields. It is a list of issues that your organization works on or 
tracks. 

• Volunteer Interests - a list of volunteer activities that your members can take on. 

Constituent Info - Organizations 

• Constituent Type - Org 
Grant Info 

• Funding Areas - this custom field uses the same set of options for Issue Interest and 
Funder Issue Interest. 

Participant Info 

• Participant Campaign Code - this custom field uses the same set of options as the 
Contribution Campaign Code, Event Campaign Code, Activity Campaign Code and 
Membership Source Code fields. Delete the example campaigns and add your own. This 
is the mechanism CiviEngage uses to connect a contact's participation across all these 
different actions. For example, a Campaign called "House Party 10-1-2010" could have an 
Event tied to it, a participant of that Event tied to it, an activity when an organizer calls 
a contact inviting them to attend an Event, a membership entry when they become 
members at the Event and a contribution when they pay their dues. 

Contribution Source 

• Contribution Campaign Code - see Participant Campaign Code. 

• Contribution Campaign Method - this custom field uses the same set of options as 
Membership Source Campaign. Add different types of interactions or locations where 
you would be engaging potential members and donors. 

Event Details 

• Event Contact Person - also used for Staff Responsible. Add all appropriate people to 
this list. 

• Event Campaign Code - see Participant Campaign Code. 

Activity Source Details 

• Activity Campaign Code - see Participant Campaign Code. 

Organizational Details 

This custom group is used to store information that is specific to organizations. There is only 
one example currently. 

• Rating - if you need to evaluate organizations in some way, change the options to reflect 
that. 

Demographics 
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• Ethnicity 

• Primary Language - this custom field uses the same set of options as Secondary 
Language. Only one entry can be selected for each contact for this field. 

• Secondary Language - also used for Primary Language, but as many choices as needed 
can be checked. 

Media Info - Org 

This custom group is only applicable to the New Media Outlet contact subtype. 

• Media Type - Org - this custom field uses the same set of options as Media Type - Ind: 
TV, Radio, Wire, Newspaper, Magazine 

Media Info - Ind 

This custom group is only applicable to the New Media Contact contact subtype. 

• Media Type - Ind - this custom field uses the same set of options as Media Type - Org 

• Beat - this refers to the general category of topics that a media contact covers, such as 
local government, education, neighborhoods, religion, labor, etc. 

• Media Issue Interest - uses the same option list as Issue Interest. As you come to know 
a reporter, you will learn the issues they are particularly interested in, even if it differs 
from their assigned beat. 

Elected Info 

This custom group is only applicable to the New Elected Official contact subtype. 

• Elected Level - the governmental body the individual is part of (City Council, state 
legislature, mayor, etc.) 

• Role - Whether the contact is the elected official, or the official's staff, spokesperson, 
etc. 

Funder Info 

This custom group is only applicable to the New Funder contact subtype. 

• Funder Issue Interest - this custom field uses the same set of options as Issue Interest 
and Funding Areas. 

Membership Source Details 

• Membership Source Code - Uses the same codes as the Participant Campaign Code and 
Contribution Campaign Code. 

• Membership Source Campaign - also used for contributions. Add different types of 
interactions or locations where you would be engaging potential members and donors. 
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ESSENTIAL TASKS 

This chapter provides instructions on how to do some of the common tasks associated with 
the CiviEngage module. 

PRINTING A WALK LIST 

CiviEngage offers a report that allows you to easily print walk lists for folks who are doing 
canvassing, Get Out the Vote (GOTV) or other door knocking activities. 

1. If you want to use Groups or Smart Groups to develop your walk list, be sure to create 
the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the walk list report. Choose whether you want the Country or Email field to 
display. 

4. Scroll down to the "Set Filters" section. You must select a filter to obtain results. All 
your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the report results, but if you click on "Print Preview" you will see your walk list. 
You can use your browser's Print Preview feature to see the walk list on a per-page 
basis. 

PRINTING A PHONE LIST 

CiviEngage offers a report that allows you to easily print phone lists for folks who are doing 
phone banks or other mass phoning activities. 

1. If you want to use Groups or Smart Groups to develop your phone list, be sure to 
create the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the phone list report. Choose the columns you want to display from the 
template screen. 

4. Scroll down to the "Set Filters" section. You must select a filter in order to obtain 
results. All your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the results but if you click on "Print Preview" you will see your phone list. You can 
now use your browser's Print Preview feature to see the phone list on a per-page basis. 

CREATE A CAMPAIGN SOURCE CODE 

In order to use CiviEngage effectively, you need to create "campaigns" that you connect all 
your activities to. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Participant Info in the list and click the corresponding "View and Edit Custom Fields" 
link. This gives you a list of Custom Fields. 

3. Find Participant Campaign Code and click the "Edit Multiple Choice Options" link. Now you 
are seeing a list of the interests. 

4. Scroll down and click on "New Option" and add your new campaign. 

Please note that this new campaign code will now be available for Event, Membership and 
Contribution Campaign Codes as well as in the Participant Campaign Code that it was just 
created in. 

ADD AN ISSUE INTEREST 
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To better understand and track the areas that your members and constituencies are 
interested in working on, CiviEngage provides a field that collects this information. Customize 
this list to meet the needs of your particular organization. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Grassroots Info in the list and click on the corresponding "View and Edit Custom 
Fields" link. This gives you a list of Custom Fields. 

3. Find Issue Interest and click the "Edit Multiple Choice Options" link. Now you are seeing a 
list of the interests. 

4. Scroll down and click "New Option" and add your new interest. 

Please note that this new issue will also appear in Funding Areas and Funder Issue Interest as 
well as in the Issue Interest that it was just created in. 

TRACK WALK LIST/CALL LIST RESPONSES 

Responses to the questions your canvassers or phone bankers ask are tracked in an 
individual's activity record. The text of the questions are tracked in the event record. In order 
to properly configure this, start with creating the event. 

1. Click on Events -> New Event. 

2. Choose Campaign for your Event Type, which will let you see the Event Campaign Details 
section. 

3. Scroll down to the Event Campaign Details section and add the text to the questions for 
this particular campaign. 

4. You will also want to add an Event Campaign Code, which is in the Event Details section. 

Next you would go to a contact record to create a "Door Knock" or "Phone Call" activity and 
finish configuring this functionality. 

1. Go to a contact's record and click on "new activity." 

2. Choose "Phone Call" or "Door Knock" and you will get the Activities screen. 

3. Scroll down and click on the Call List Responses section. 

4. Now you can record the responses. 

5. You then add the Activity Campaign Code in the Activity Source Details section. Make 
sure you choose the same campaign as you did for the Event. 
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PRINT AN ACTIVITY REPORT 

One of the features of CiviEngage is the ability to track the different activities that your 
members are engaged in. Use the activity report to better understand what your members 
are doing. 
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1. Click on Reports -> Create Reports from Template . 

2. Choose the Activity Report. This brings up the Activity Report Template. You are now 
looking at all the options available for printing a report based on the activities CiviEngage 
offers that your contacts are engaged in. 

3. The first section lists the columns that are available for your report. Use the check 
boxes to decide what information you want your report to show. The default values are 
Assignee Contact Name , Target Contact Name , Activity Type , Subject, Activity Date and 
Activity Status . You can choose columns from Walk List Responses, Leadership Level 
(from Activities), Call List Responses, Proposal Info or Activity Source Details. 

If, for example, you want a report of Walk List Responses from a specific campaign, you 
would check boxes from the Walk List Responses section and choose the Activity 
Campaign Code from the Activity Source Details section. Please note that the default 
value for Activity Date is "this month." If you want a different range of dates you have 
many options. Click on "this month" and you will see all the options available. Included is 
Date Range, where you can choose a specific range of dates. 

4. The next section allows you to group your data by the Source Contact (the default 
value), Activity Date or Activity Type . Check the appropriate box for your report. 

5. The final section is for filtering your data. Here you can choose data from any of the 
activity fields that CiviEngage offers. 

To continue our example, you might choose to include data where the first two Walk 
List questions were answered yes. Choose Y in the appropriate boxes and scroll down to 
the Activity Source Detail section and choose the appropriate Activity Campaign Code . 
Click Preview Report and view your results. 

6. Once you have your results, you have a number of options. You can "Preview" the 
report, "Preview" the PDF of the report, "Preview" the CSV (export your report into a 
spreadsheet), or "Add the contacts to a group." 

SEARCH FOR ACTIVITIES 

The are a number of ways to search for the activities that you create using CiviEngage: 

• Run a report, as explained above 

• Use the Find Activities search option 

• Use the CiviCRM Advanced Search 

• Run an Activity Search, which is in Custom Searches. 

Using the Find Activities search option 

1. Click on Search -> Find Activities . 

2. You are presented with a number of search criteria options. You can enter the name or 
email address of a contact in the database. You can choose one or more activity types. 
You can add a range of dates during which activities happened. You can search for 
contacts in specific Activity Roles: With, Created By and Assigned to. You can look for 
specific subjects, test activities or by the status of the activity. Each criterion you select 
will narrow your search results. 

3. Click Search and you will get to the Search Results screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using Advanced Search to find Activities 
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1. Click on Search -> Find Contacts - Advanced Search . 

2. Scroll down to the Activities section and click on it. Here you find all the options available 
in CiviEngage for activities. 

3. Once you choose your search options and click Search you will get to the Search Results 
screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using the Custom Search: Activity Search 

1. Click on Search -> Custom Searches... -> Activity Search . 

2. You are presented with different criteria by which you can search for information. Enter 
your search terms and click Search. 

3. The Search Results provides the Name of the person, the Status, Type and Subject of 
the Activity and who assigned the activity. You also have a button for viewing and 
editing each activity record. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 
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41. 



WHAT IS CIVIREPORT? 



CiviReport allows you to create, run and schedule reports based on the data CiviCRM has 
about your contacts and their interactions with your organisation. Many report templates are 
designed to work with a specific CiviCRM component, such as CiviContribute or CiviCase. 

CiviCRM comes with a number of predefined report templates that are used to create 
reports. For example, the Membership Report template can be used to create a report that 
shows all student members that have joined your organisation within the past year. 

CiviCRM's predefined report templates are built to satisfy the basic needs of non-profits and 
organisations. Each new version of CiviCRM will include further report templates, but if you 
can't find the right template for your requirement, you can extend CiviCRM by writing a new 
template yourself - and contribute it back to the CiviCRM community to share the benefit of 
your work. 

Writing a new report template requires some PHP and SQL skills. A well-written template will 
be flexible enough to meet your specific needs as well as the needs of others. Techniques for 
developing report templates are explained in the section of this book which covers methods of 
extending and customising CiviCRM. 

REAL WORLD SCENARIOS 

Reports help your organisation to evaluating its impact and achieve its mission. Here are some 
reports examples: 

Evaluating turnout for an event 

An organisation wants to attract young people to their annual 'Community Organising and 
Youth Leadership workshop' They decide to announce the event three months in advance to 
ensure a good turnout. Lead staff or organisers will use the Event Participant Report 
throughout the registration process to determine if they need to do more outreach to attract 

m. 

Here is a work flow describing how the organisation's staff will use this report. 

1. A lead staff person uses pecific criteria, such as youths under the age of 25 based in the 
target area, to identify contacts to invite to the event. 

2. Lead staff then email and phone the identified contacts to invite them to register and 
attend the event. 

3. During the three months before the event, a lead organiser views the Event Participant 
Report at the end of each week to see how many have registered and to determine 
what other strategies could be used to increase the turnout. The lead organiser may 
also want to know the roles of the participants, such as who and how many will be 
speakers or volunteers. 

4. At the end of the event, the lead organiser will view the Event Participant Report again 
to see how many actually attended the event, as well as how many registered but didn't 
attend. Organisers may then want to follow up those contacts who registered but didn't 
attend, to determine whether there were any barriers to attending such as the cost of 
the event, lack of transportation or lack of interest in the topics scheduled for the 
workshop. 

Determining total contributions for all people in a household 

A non profit keeps records of individuals organised by households. A common situation will be 
that the husband in the household has attended a numbe of paid events, and their wife has 
also registered for other events, and made seperate donations. 
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Staff at the organisation want to see the total contributions received from everyone in the 
household so that when someone calls the office to inquire about a donation or event 
payment made by someone else in the family, all the relevant information is at hand. Staff 
run the Donation Summary Report (Household) and fill in the name of the household to find 
all contributions and find all relevant information and answer the caller's questions. 

Targeting a mailing for fundraising 

Your organisation has launched a capital campaign to raise money for a new shelter. The 
development director wants to reach out to donors who made a large donation last year but 
haven't given money this year. 

1. She creates an instance of the LYBUNT report ("Last year but not this year") which 
filters data to show people who gave more than 500 EUR last year. 

2. She runs the report and uses the "Add to Group" button to put these donors in a new 
group. 

3. Then she sends an email to everyone in the group with information about the capital 
campaign. 

4. She adds the report to her CiviCRM Dashboard so she can review progress getting this 
group of prior donors to contribute to the campaign. 
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PLANNING WITH CIVIENGAGE 

CiviEngage packages a set of custom data groups and fields, reports, and other features for 
use in civic engagement and community organizing work. This chapter will describe the general 
concepts and planning needed to use CiviEngage effectively. 

WHAT YOU NEED TO KNOW 

The following are concepts, custom fields and values to keep in mind when preparing to use 
CiviEngage. 

Campaign Source Code 

Campaign Source Codes are descriptive values used to identify related activities, events, 
contributions, and memberships and map how these activities and transactions are linked 
together. Campaign Source Codes are also useful for identifying these sets of activities or 
transactions as part of a larger campaign, project, or program. 

For example, an organization is conducting a door knock canvass around a particular issue 
during a specific range of dates. The organization may want to use campaign source codes to 
link together the activities (where responses to door knock canvass questions are captured), 
the event (the door knock canvass campaign itself), and any contributions made during the 
canvass to be able to analyze the effectiveness of the campaign. 

Activity, Event, Contribution, Participant, and Membership records each contain a custom field 
to store a Campaign Source Code, that all share a common option list where Campaign Source 
Code values can be added and edited. 

Your organization can establish a standard method for creating new Campaign Source Codes 
so that the codes are consistent and easy to sort and understand at a glance. For example, 
you can specify that annual campaigns always include the year at the either the beginning or 
the end of the Campaign Source Code, not both, so that you don't wind up with "2009 Annual 
Campaign" and "Annual Campaign 2010." 

Issue Interests 

Issue Interests are issues that your organization works on or tracks. They are included in 
CiviEngage as a single option list shared across multiple contexts: 

• Grassroots Info: Issue Interests for individuals 

• Media Issue Interests for media contacts 

• Funder Issue Interests for funders 

• Grant Info: Funding Areas for organizations 

It is important to remember that despite appearing with different labels in these different 
contexts, you are still dealing with just one shared list of options. 

In planning to use CiviEngage you should come up with a list of distinct issues that are 
important to your organization and that you will want to utilize when tracking individuals' 
interest in your organization's work, the issues that your media contacts may be interested in 
covering, funders' general interests and the specific areas of work included in particular grants. 

Volunteer Interest 
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Volunteer interests are activities that your organization's volunteers can take on and 
participate in; you can indicate each individual's interest in participating in these ways. They 
are included in CiviEngage as an option list. In planning to use CiviEngage you should establish a 
list of your organization's current volunteer activities as well as any activities that you are 
planning to launch in the future. Some examples of volunteer interests are canvassing, phone 
banking, and tabling. 

Cleaning your Address Data 

Cleaning your address data means standardizing addresses to conform to the conventions 
defined by the United States Postal Service's Standards for Addresses. Standardizing how 
addresses are entered into CiviCRM will allow for more accurate search results when searching 
by address and is essential to generate accurate Walk List reports. CiviCRM will parse 
addresses based on the USPS standards. To find out more about how Address Parsing is 
handled and used in CiviCRM, refer to the Address Parsing chapter of this book. When adding 
or editing contacts you will be entering or editing address elements including street number, 
street name, and Apt/Unit/Suite number according to these standards. 

When planning to import pre-existing data into CiviCRM for use in CiviEngage it is essential that 
you plan to clean up address data before importing. 

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 
at http://pe.usps.com/text/pub28/welcome.htm . 

TRACKING CIVIC ENGAGEMENT AND CAMPAIGNS 

CiviEngage is designed to manage interactions with constituents around an organization's civic 
engagement and base-building work, such as door knock canvassing and phone banking. There 
are several concepts and details to consider when preparing for these types of campaigns. 

Working with Your Universe of Contacts 

In preparing for your campaign, you will need to identify the audiences you will be targeting for 
your door knock canvass or phone bank in CiviCRM. CiviCRM uses Smart Groups and regular 
Groups as the mechanisms to target specific groups of contacts. Here are a couple of 
examples of how you can use Smart Groups and regular Groups for targeting during your 
campaign: 

• You can use Smart Groups to identify contacts you want to target based on specific 
criteria, such as voter demographics, issue interests, primary language spoken, etc. 

• You can track voter demographics about your contacts using the custom data group 
called Voter Info 

• You can use Groups to identify contacts who subscribe to a particular newsletter or 
issue to do an email blast about your campaign. 

• You can then use these Smart Groups and regular Groups to generate your walk list or 
phone bank list. 

Learn more about working with Smart Groups and regular Groups in the "Tags and Groups" 
chapter of this book. 

Preparing a Campaign Event 

To prepare a campaign event in CiviCRM, there are several setup items you may want to 
consider: 



189 



• Define a specific Campaign Source Code for your event. This Campaign Source Code will 
be used for the event and the activity which holds the individual responses gathered 
during the door knock canvass or phone bank campaign. 

• When you set up your event with the Event Type set to "Campaign" you can record 
the questions being asked during the campaign in the Event Campaign Details area. 

• Decide how you want to identify participants in the campaign event. Maybe you only 
want to identify the staff and volunteers who will be involved in conducting the door 
knock canvass or phone bank. Maybe you'll want to add the targeted contacts as 
participants. Activities will be used to record the responses of each individual contacted 
during the campaign as well as the campaign source code related to the campaign, so it 
may not be necessary to add these contacts to the event. In either case, it is 
recommended to also record the Campaign Source Code in the participant's record in 
the Participant Info area. 

• When capturing responses from each individual during the campaign, consider how you 
plan on getting the data back into CiviCRM. If the plan is to enter data one contact at a 
time, which may make sense for phone banking, you will need to record the response in 
the individual's activity record, with the Activity Type of "Door Knock" or "Phone" in 
the Walk List Responses or Call List Responses area. But if you plan on entering 
batches of data at a time, then you will need to plan to import the responses using the 
Import Activities function. 

Working with Voter History 

When using CiviEngage, plan how you will manage voter history and other voter information 
collected during a voter engagement or electoral cycle. Many organizations have access to a 
voter file from which they manage all their voter engagement work outside of CiviCRM. Once 
the voter engagement or electoral campaign is over and voter information is updated with 
who voted and other demographics, organizations most often will only want to keep 
information on the actual contacts they made during the campaign. In this case, only those 
selected records from the voter file and additional voter information, such as responses to 
specific electoral campaign questions, will be imported and maintained in CiviCRM. These voter 
records then become contacts that organizers will continue to engage and target with base- 
building efforts. 

If you wish to collect voter contacts with their demographics, history, and additional 
information, first import voter contacts (with their contact information and demographics) into 
the Voter Info custom group. Then import additional information as Activities, such as 
responses to electoral campaign canvass questions. 

MOBILIZING INDIVIDUALS TO ATTEND AN EVENT 

The Participant Info custom data group that comes with CiviEngage contains fields that hold 
information about prospective event participants, including a history of interactions between 
your organization and prospective participants. Use this information (such as needs for 
childcare or rides) to bring these individuals to your events. Tracking the history of your 
organization's contact with individuals around events such as an annual membership meeting, 
a direct action, or leadership training can help you to understand the effectiveness of your 
outreach methods and determine how committed or engaged an individual is based on if the 
individual actually attends events after multiple contacts. 

This feature is mostly useful for organizers or staff who have a list of individuals they are 
recruiting to attend an event through multiple phone calls or face-to-face meetings. The 
following CiviCRM tasks could be used to mobilize individuals: 
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1. Conduct a basic or advanced search or use Groups and Smart Groups to create a list of 
the contacts you want to mobilize or invite to the event. 

2. From the search results or Group Contacts screen, you can add the list of contacts to 
the event by selecting Add Contacts to Events from the Actions list. To find out more 
about how to add contacts to events, refer to the Managing Participants chapter in the 
Events section in this book. 

3. Once you add the contacts to the event, you can enter participant information or 
responses from multiple interactions in the Participant Info area in a contact's 
participant record. You can either enter information for one participant by editing the 
participant record itself, or you can add information for a list of participants at one time. 
For example, if you plan to call through your list by viewing the participant list from the 
event listing, you could use Batch Update Participants Via Profile and select one of 
the following custom profiles provided by CiviEngage: 

• Update Event Invite Responses - to record responses from multiple contacts with the 
participant. 

• Update Participant Info - to record general information about participants, such as if 
they need childcare or rides to the event. 

TRACKING FUNDERS AND FOUNDATIONS 

You can track information about and due dates for grant proposals, letters of inquiries, and 
reports for funders by adding an activity related to the funder's contact record and choosing 
from the Proposal, Letter of Inquiry, or Report activity types. 

You can also tailor information about an individual funder, such as their funding areas and 
issue interests, using the Funder Info custom group. In order to view the Funder Info tab, you 
will need to use the Individual sub-contact type, Funder, when you create a new contact that 
is identified as a funder. 

You can tailor information about a foundation (organization record), such as their program 
areas for funding, using the Grant Info custom group. 

TRACKING MEDIA CONTACTS 

As part of civic engagement and community organizing work, it can be useful to track 
information about your media contacts in CiviCRM, especially if you want to know which media 
contacts or outlets are interested in your organization's issues, or have written articles about 
your work, or for identifying who to contact when you want to publicize the work the 
organization is undertaking. 

You can tailor information about an individual media contact, such as their media type (e.g., 
TV, Newspaper, Photographer, etc.), issue interests and beat using the Media Info - Ind 
custom group. Use the Individual sub-contact type, Media Contact, when you create a new 
contact for a media contact. You can then view and edit the Media Info - Ind tab. 

You can also tailor information about a media outlet (organization) such as their media type 
(e.g., TV, Newspaper, Magazine, etc.) using the Media Info - Org custom group. As with the 
individual media person, use the Organization sub-contact type, Media Outlet, when you 
create a new contact for a media outlet. You can then view and edit the Media Info - Org 
tab. 

TRACKING ELECTED OFFICIALS 

Identifying and collecting information about your elected officials could be useful for your 
community organizing and civic engagement work. You may want to know who is an elected 
official in a specific district, or who to contact on their staff, such as the scheduler, or 
spokesperson. 
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You can tailor information about an individual elected official, such as their elected position 
(e.g., city council, Senate, etc.) and their role using the Elected Info custom group. Use the 
Individual sub-contact type, Elected Official, when you create a new contact for an elected 
official. You can then view and edit the Elected Info tab. Remember that staffers, schedulers, 
or spokespeople for an elected official can be entered as the Elected Official subtype. 

REPORTING AND ANALYSIS 

There are two reports packaged with CiviEngage: Walk List and Phonebank List. In addition, 
the Activity Report is enhanced to filter custom activity fields such as those associated with 
the custom group Call List Responses and Walk List Responses. 

The Walk List report allows you to view, print, or export an individual's contact information 
and demographics such as Member Type, Sex, Age, Party Registration, Voter history, along 
with response codes and notes where a volunteer can collect responses during a door knock 
canvass. 

The Phonebank List report is similar to the Walk List report except that this report is used 
exclusively during a phonebank and contain response codes pertaining to phone responses. 

The Walk List and Phonebank List reports are used to collect information during a campaign to 
later be imported or batch entered back into CiviCRM. 

The Activity Report is enhanced to allow you to search, view, print, or export for specific 
responses from a door knock canvass or phonebank campaign. Use this report not only to 
analyze the effectiveness of your campaign (e.g., how many people you contacted and 
collected responses from) but also to analyze responses from your constituency around an 
issue, or to determine whether individuals may become more involved with your 
organization. 

Disabling vs. Deleting Custom Data 

If you decide you don't need to use or view particular custom groups, fields, or values, we 
strongly recommend that you disable the group, field, or value rather than delete them. The 
Walk List and Phonebank List reports rely on these fields, so deleting certain custom data 
could potentially "break" the reports. 
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CONFIGURATION 

You will need to configure both Drupal and CiviEngage to use the module. 

CONFIGURING CIVICRM FOR CIVIENGAGE 

CiviEngage can be configured using the following CiviCRM core features: 
Custom Data Groups 

Configure custom data groups and fields to track voter demographics, issue interests, 
leadership levels, volunteer interests, and information about funders, media contacts, and 
elected officials. 

Contact Subtypes 

CiviEngage takes advantage of CiviCRM contact subtypes to expose custom data groups 
associated only with specific subtypes. The following are new contact subtypes: 

Individual subtypes: 

• Media Contact - will expose a contact tab containing information specific to media 
contacts, such as their media type (e.g. Newspaper, Radio, TV, etc.), their "Beat," and 
the media issue interests 

• Elected Official - will expose a contact tab containing information specific to elected 
officials, such as their elected level (e.g. City Council, Senate, etc.) and the role (e.g. 
scheduler, spokesperson, etc.) 

• Funder - will expose a contact tab containing information specific to funders, such as 
their program areas and their issue interests. 

Organization subtypes: 

• Media Outlet - will expose a contact tab containing information about their type of 
media, such as TV, Radio, Wire, Newspaper, Magazine, etc. 

Campaign Source Codes 

CiviEngage uses Campaign Source Codes that you can tailor to describe and track related 
activities, events, event participants, contributions, or memberships. Campaign Source Codes 
can be used to describe a group of related activities, events, contributions, or memberships 
for a specific campaign, project, or program. 

Note: A "Campaign" does not necessarily mean a formal campaign, but can also generally be 
defined as a specific project, program, or organizing activity. 

Door Knock Canvass and Phone Bank Tracking 

• Events used for Door Knock Canvass or Phone Bank - Use the Campaign Event Type to 
expose Event custom fields that allows you to store up to four specific questions being 
asked during a door knock canvass or phone bank. 

• Activities used to Collect Responses from Door Knock Canvass or Phone Bank 
Campaigns - Use the Door Knock and Phone Call Activity Types to expose custom 
fields where you can collect an individual's responses during a door knock canvass or 
phone bank. 

Reports 
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• Walk List Report - view, print or export certain demographic and other constituent 
information in a specific geographic area to collect responses to be used during a door 
knock canvass. The Walk List Report takes advantage of the optional address parsing 
feature to build the report. 

• Call List Report - view, print or export certain demographic and other constituent 
information along with an area to collect responses to be used during a phone bank. 

• Activity Report - includes filters for activity custom fields so that you can build a report 
of specific activities based on criteria about your constituency, such as creating a report 
to analyze particular responses from a door knock canvass or phone bank. 

Grant Proposal and Report Tracking 

CiviEngage uses the Proposal, Letter of Inquiry and Report Activity Types to expose custom 
fields to track information and schedules for proposals, letters of inquiries and reports related 
to an individual funder or foundation. 

Custom Profiles 

CiviEngage configures several custom profiles for easier batch updating of individual or 
organization information, such as voter demographics, issue interests, volunteer interests, or 
event participant information. To learn more about profiles, please refer to the "Profiles" 
section of the book. 

CONFIGURING CIVIENGAGE 

When you install CiviEngage a number of custom fields are automatically created. These fields 
are designed to support your community organizing work. Most of these fields are multiple 
choice fields which have been pre-populated with sample options. Before you start using 
CiviEngage, you need to review and modify the supplied options to meet your needs. 

Begin by going to Administer -> Customize -> Custom Data in the navigation menu. In the 
following list bolded items are Group Header entries in the Custom Data screen. The bulleted 
items are custom fields under those Group Headers that have been added by CiviEngage; the 
other fields under these group headers are standard to CiviCRM. The choices for these custom 
fields should be edited before you use CiviEngage. You should add, delete, or edit the available 
options for each custom field to make them better fit your organization's needs. 

Communications Details 

• Best Time to Contact 

Voter Info 

All of the fields in this custom data group are added by CiviEngage, so you should review and 
edit them all to suit your needs. You may also want to add specific local voter fields that apply 
to you. 

Constituent Info - Individuals 

• Constituent Type 

• Staff Responsible - note that the values for this field are also used for Event Contact 
Person. Replace the sample names in the list with your staff, member or volunteer 
coordinators, and other folks that have individuals assigned to them. 

• How Started - edit this list to fit the ways in which members are brought into your 
organization. 

Grassroots Info 
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• Member Status - three status choices included by default. Think about other member 
statuses that might work for your organization and add or remove as needed. 

• Leadership Level - The default options for tracking an individual's leadership level within 
your organization are 1-5. Change this to match however your organization tracks this 
information. 

• Issue Interest - this custom field uses the same set of options as the Funding Areas and 
Funder Issue Interest fields. It is a list of issues that your organization works on or 
tracks. 

• Volunteer Interests - a list of volunteer activities that your members can take on. 

Constituent Info - Organizations 

• Constituent Type - Org 
Grant Info 

• Funding Areas - this custom field uses the same set of options for Issue Interest and 
Funder Issue Interest. 

Participant Info 

• Participant Campaign Code - this custom field uses the same set of options as the 
Contribution Campaign Code, Event Campaign Code, Activity Campaign Code and 
Membership Source Code fields. Delete the example campaigns and add your own. This 
is the mechanism CiviEngage uses to connect a contact's participation across all these 
different actions. For example, a Campaign called "House Party 10-1-2010" could have an 
Event tied to it, a participant of that Event tied to it, an activity when an organizer calls 
a contact inviting them to attend an Event, a membership entry when they become 
members at the Event and a contribution when they pay their dues. 

Contribution Source 

• Contribution Campaign Code - see Participant Campaign Code. 

• Contribution Campaign Method - this custom field uses the same set of options as 
Membership Source Campaign. Add different types of interactions or locations where 
you would be engaging potential members and donors. 

Event Details 

• Event Contact Person - also used for Staff Responsible. Add all appropriate people to 
this list. 

• Event Campaign Code - see Participant Campaign Code. 

Activity Source Details 

• Activity Campaign Code - see Participant Campaign Code. 

Organizational Details 

This custom group is used to store information that is specific to organizations. There is only 
one example currently. 

• Rating - if you need to evaluate organizations in some way, change the options to reflect 
that. 

Demographics 
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• Ethnicity 

• Primary Language - this custom field uses the same set of options as Secondary 
Language. Only one entry can be selected for each contact for this field. 

• Secondary Language - also used for Primary Language, but as many choices as needed 
can be checked. 

Media Info - Org 

This custom group is only applicable to the New Media Outlet contact subtype. 

• Media Type - Org - this custom field uses the same set of options as Media Type - Ind: 
TV, Radio, Wire, Newspaper, Magazine 

Media Info - Ind 

This custom group is only applicable to the New Media Contact contact subtype. 

• Media Type - Ind - this custom field uses the same set of options as Media Type - Org 

• Beat - this refers to the general category of topics that a media contact covers, such as 
local government, education, neighborhoods, religion, labor, etc. 

• Media Issue Interest - uses the same option list as Issue Interest. As you come to know 
a reporter, you will learn the issues they are particularly interested in, even if it differs 
from their assigned beat. 

Elected Info 

This custom group is only applicable to the New Elected Official contact subtype. 

• Elected Level - the governmental body the individual is part of (City Council, state 
legislature, mayor, etc.) 

• Role - Whether the contact is the elected official, or the official's staff, spokesperson, 
etc. 

Funder Info 

This custom group is only applicable to the New Funder contact subtype. 

• Funder Issue Interest - this custom field uses the same set of options as Issue Interest 
and Funding Areas. 

Membership Source Details 

• Membership Source Code - Uses the same codes as the Participant Campaign Code and 
Contribution Campaign Code. 

• Membership Source Campaign - also used for contributions. Add different types of 
interactions or locations where you would be engaging potential members and donors. 
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ESSENTIAL TASKS 

This chapter provides instructions on how to do some of the common tasks associated with 
the CiviEngage module. 

PRINTING A WALK LIST 

CiviEngage offers a report that allows you to easily print walk lists for folks who are doing 
canvassing, Get Out the Vote (GOTV) or other door knocking activities. 

1. If you want to use Groups or Smart Groups to develop your walk list, be sure to create 
the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the walk list report. Choose whether you want the Country or Email field to 
display. 

4. Scroll down to the "Set Filters" section. You must select a filter to obtain results. All 
your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the report results, but if you click on "Print Preview" you will see your walk list. 
You can use your browser's Print Preview feature to see the walk list on a per-page 
basis. 

PRINTING A PHONE LIST 

CiviEngage offers a report that allows you to easily print phone lists for folks who are doing 
phone banks or other mass phoning activities. 

1. If you want to use Groups or Smart Groups to develop your phone list, be sure to 
create the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the phone list report. Choose the columns you want to display from the 
template screen. 

4. Scroll down to the "Set Filters" section. You must select a filter in order to obtain 
results. All your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the results but if you click on "Print Preview" you will see your phone list. You can 
now use your browser's Print Preview feature to see the phone list on a per-page basis. 

CREATE A CAMPAIGN SOURCE CODE 

In order to use CiviEngage effectively, you need to create "campaigns" that you connect all 
your activities to. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Participant Info in the list and click the corresponding "View and Edit Custom Fields" 
link. This gives you a list of Custom Fields. 

3. Find Participant Campaign Code and click the "Edit Multiple Choice Options" link. Now you 
are seeing a list of the interests. 

4. Scroll down and click on "New Option" and add your new campaign. 

Please note that this new campaign code will now be available for Event, Membership and 
Contribution Campaign Codes as well as in the Participant Campaign Code that it was just 
created in. 

ADD AN ISSUE INTEREST 
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To better understand and track the areas that your members and constituencies are 
interested in working on, CiviEngage provides a field that collects this information. Customize 
this list to meet the needs of your particular organization. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Grassroots Info in the list and click on the corresponding "View and Edit Custom 
Fields" link. This gives you a list of Custom Fields. 

3. Find Issue Interest and click the "Edit Multiple Choice Options" link. Now you are seeing a 
list of the interests. 

4. Scroll down and click "New Option" and add your new interest. 

Please note that this new issue will also appear in Funding Areas and Funder Issue Interest as 
well as in the Issue Interest that it was just created in. 

TRACK WALK LIST/CALL LIST RESPONSES 

Responses to the questions your canvassers or phone bankers ask are tracked in an 
individual's activity record. The text of the questions are tracked in the event record. In order 
to properly configure this, start with creating the event. 

1. Click on Events -> New Event. 

2. Choose Campaign for your Event Type, which will let you see the Event Campaign Details 
section. 

3. Scroll down to the Event Campaign Details section and add the text to the questions for 
this particular campaign. 

4. You will also want to add an Event Campaign Code, which is in the Event Details section. 

Next you would go to a contact record to create a "Door Knock" or "Phone Call" activity and 
finish configuring this functionality. 

1. Go to a contact's record and click on "new activity." 

2. Choose "Phone Call" or "Door Knock" and you will get the Activities screen. 

3. Scroll down and click on the Call List Responses section. 

4. Now you can record the responses. 

5. You then add the Activity Campaign Code in the Activity Source Details section. Make 
sure you choose the same campaign as you did for the Event. 
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PRINT AN ACTIVITY REPORT 

One of the features of CiviEngage is the ability to track the different activities that your 
members are engaged in. Use the activity report to better understand what your members 
are doing. 
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1. Click on Reports -> Create Reports from Template . 

2. Choose the Activity Report. This brings up the Activity Report Template. You are now 
looking at all the options available for printing a report based on the activities CiviEngage 
offers that your contacts are engaged in. 

3. The first section lists the columns that are available for your report. Use the check 
boxes to decide what information you want your report to show. The default values are 
Assignee Contact Name , Target Contact Name , Activity Type , Subject, Activity Date and 
Activity Status . You can choose columns from Walk List Responses, Leadership Level 
(from Activities), Call List Responses, Proposal Info or Activity Source Details. 

If, for example, you want a report of Walk List Responses from a specific campaign, you 
would check boxes from the Walk List Responses section and choose the Activity 
Campaign Code from the Activity Source Details section. Please note that the default 
value for Activity Date is "this month." If you want a different range of dates you have 
many options. Click on "this month" and you will see all the options available. Included is 
Date Range, where you can choose a specific range of dates. 

4. The next section allows you to group your data by the Source Contact (the default 
value), Activity Date or Activity Type . Check the appropriate box for your report. 

5. The final section is for filtering your data. Here you can choose data from any of the 
activity fields that CiviEngage offers. 

To continue our example, you might choose to include data where the first two Walk 
List questions were answered yes. Choose Y in the appropriate boxes and scroll down to 
the Activity Source Detail section and choose the appropriate Activity Campaign Code . 
Click Preview Report and view your results. 

6. Once you have your results, you have a number of options. You can "Preview" the 
report, "Preview" the PDF of the report, "Preview" the CSV (export your report into a 
spreadsheet), or "Add the contacts to a group." 

SEARCH FOR ACTIVITIES 

The are a number of ways to search for the activities that you create using CiviEngage: 

• Run a report, as explained above 

• Use the Find Activities search option 

• Use the CiviCRM Advanced Search 

• Run an Activity Search, which is in Custom Searches. 

Using the Find Activities search option 

1. Click on Search -> Find Activities . 

2. You are presented with a number of search criteria options. You can enter the name or 
email address of a contact in the database. You can choose one or more activity types. 
You can add a range of dates during which activities happened. You can search for 
contacts in specific Activity Roles: With, Created By and Assigned to. You can look for 
specific subjects, test activities or by the status of the activity. Each criterion you select 
will narrow your search results. 

3. Click Search and you will get to the Search Results screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using Advanced Search to find Activities 
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1. Click on Search -> Find Contacts - Advanced Search . 

2. Scroll down to the Activities section and click on it. Here you find all the options available 
in CiviEngage for activities. 

3. Once you choose your search options and click Search you will get to the Search Results 
screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using the Custom Search: Activity Search 

1. Click on Search -> Custom Searches... -> Activity Search . 

2. You are presented with different criteria by which you can search for information. Enter 
your search terms and click Search. 

3. The Search Results provides the Name of the person, the Status, Type and Subject of 
the Activity and who assigned the activity. You also have a button for viewing and 
editing each activity record. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 
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45. 



WHAT IS CIVIENGAGE? 



CiviEngage is a drupal module that enhances CiviCRM's core functions for non-profits focused 
on community organizing and civic engagement work. 

PURPOSE 

CiviEngage was built to aid community organizing, base-building and civic engagement, 
specifically with regards to managing walk lists for door-to-door campaigns and caller lists for 
phone banks. 

CiviEngage provides: 

• A package of custom fields, reports and features to track the history of engagement, 
involvement, and activities of constituents over time 

• A model of how to conceptualize and best organize information about individual 
constituents, organizations and methods of tracking their history of interaction. 

SCENARIOS 

Community organizing groups that do base-building and civic engagement work have taken 
advantage of the features in CiviEngage in various ways. The following are scenarios in which 
CiviEngage can help organizations further their ongoing community organizing. 

Mobilizing Constituents for a Direct Action 

An organization needs to mobilize several hundred people for a direct action at the state 
capitol in less than two weeks. The organizers know that the best way to contact their 
particular constituency is by phone. Organizers want to know who is coming to the direct 
action, so they can track that individual's involvement with the organization over time. 

1. Organizers will identify who they want to mobilize for direct action based on specific 
criteria and information they know about their constituency, such as geographic location, 
issue interests, volunteer interests, leadership level, etc. 

2. A staff member will create a Direct Action event in CiviCRM and add groups of 
individuals to the event. 

3. Organizers will call the list of possible participants from a Phonebank List report or 
through a participant listing and enter each call's results; such as whether they will 
attend, or if it's a wrong number, or if the organizer left a message. 

4. An organizer may contact the participants several times to ensure that they will attend 
the direct action, so the organizer will record the responses each time they attempt to 
contact the participant. Most organizers attempt to contact up to 3 times to ensure 
that the participant commits to attending. 

5. After the Direct Action event, staff can analyze how many people attended or didn't 
who said they would attend, as well as if their method of outreach was effective. 

Door Knock Canvassing 

An organization wants to engage constituents based on what they learn from individual 
responses during a door knock canvass around a particular issue, such as workers' rights. To 
find out more about how their constituencies feel about the issue and to see if they would like 
to help, the organization decides to do a door knock canvass in several neighborhoods. 
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1. Staff will define the target audience based on specific districts in a city and use 
CiviCRM's Smart Groups to build the list of people to canvass. 

2. Staff will set up a Campaign Event to record the questions that will be asked during the 
door knock canvass. 

3. Staff will identify the volunteers who will do the door knocking and then add them as 
participants to the event. This way they can track who is door knocking and what group 
or list of individuals they will be visiting. 

4. Staff will print the Walk List Report based on the Smart Group, and will also export the 
walk list information to a spreadsheet to collect the responses and identify the 
volunteer canvasser. 

5. Each volunteer canvasser will door knock the locations on the Walk List and gather 
responses on their report. At the end of the night, other volunteers will gather the Walk 
List reports, and enter the responses on the spreadsheet. Staff can then import the 
spreadsheet information back into CiviCRM. 

6. After the canvass campaign, staff can use the Activity Report to analyze campaign 
responses to determine their next step to engage their constituency in the issue. 
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PLANNING WITH CIVIENGAGE 

CiviEngage packages a set of custom data groups and fields, reports, and other features for 
use in civic engagement and community organizing work. This chapter will describe the general 
concepts and planning needed to use CiviEngage effectively. 

WHAT YOU NEED TO KNOW 

The following are concepts, custom fields and values to keep in mind when preparing to use 
CiviEngage. 

Campaign Source Code 

Campaign Source Codes are descriptive values used to identify related activities, events, 
contributions, and memberships and map how these activities and transactions are linked 
together. Campaign Source Codes are also useful for identifying these sets of activities or 
transactions as part of a larger campaign, project, or program. 

For example, an organization is conducting a door knock canvass around a particular issue 
during a specific range of dates. The organization may want to use campaign source codes to 
link together the activities (where responses to door knock canvass questions are captured), 
the event (the door knock canvass campaign itself), and any contributions made during the 
canvass to be able to analyze the effectiveness of the campaign. 

Activity, Event, Contribution, Participant, and Membership records each contain a custom field 
to store a Campaign Source Code, that all share a common option list where Campaign Source 
Code values can be added and edited. 

Your organization can establish a standard method for creating new Campaign Source Codes 
so that the codes are consistent and easy to sort and understand at a glance. For example, 
you can specify that annual campaigns always include the year at the either the beginning or 
the end of the Campaign Source Code, not both, so that you don't wind up with "2009 Annual 
Campaign" and "Annual Campaign 2010." 

Issue Interests 

Issue Interests are issues that your organization works on or tracks. They are included in 
CiviEngage as a single option list shared across multiple contexts: 

• Grassroots Info: Issue Interests for individuals 

• Media Issue Interests for media contacts 

• Funder Issue Interests for funders 

• Grant Info: Funding Areas for organizations 

It is important to remember that despite appearing with different labels in these different 
contexts, you are still dealing with just one shared list of options. 

In planning to use CiviEngage you should come up with a list of distinct issues that are 
important to your organization and that you will want to utilize when tracking individuals' 
interest in your organization's work, the issues that your media contacts may be interested in 
covering, funders' general interests and the specific areas of work included in particular grants. 

Volunteer Interest 
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Volunteer interests are activities that your organization's volunteers can take on and 
participate in; you can indicate each individual's interest in participating in these ways. They 
are included in CiviEngage as an option list. In planning to use CiviEngage you should establish a 
list of your organization's current volunteer activities as well as any activities that you are 
planning to launch in the future. Some examples of volunteer interests are canvassing, phone 
banking, and tabling. 

Cleaning your Address Data 

Cleaning your address data means standardizing addresses to conform to the conventions 
defined by the United States Postal Service's Standards for Addresses. Standardizing how 
addresses are entered into CiviCRM will allow for more accurate search results when searching 
by address and is essential to generate accurate Walk List reports. CiviCRM will parse 
addresses based on the USPS standards. To find out more about how Address Parsing is 
handled and used in CiviCRM, refer to the Address Parsing chapter of this book. When adding 
or editing contacts you will be entering or editing address elements including street number, 
street name, and Apt/Unit/Suite number according to these standards. 

When planning to import pre-existing data into CiviCRM for use in CiviEngage it is essential that 
you plan to clean up address data before importing. 

To find out more details about the USPS' Standards for addresses, refer to their Publication 28 
at http://pe.usps.com/text/pub28/welcome.htm . 

TRACKING CIVIC ENGAGEMENT AND CAMPAIGNS 

CiviEngage is designed to manage interactions with constituents around an organization's civic 
engagement and base-building work, such as door knock canvassing and phone banking. There 
are several concepts and details to consider when preparing for these types of campaigns. 

Working with Your Universe of Contacts 

In preparing for your campaign, you will need to identify the audiences you will be targeting for 
your door knock canvass or phone bank in CiviCRM. CiviCRM uses Smart Groups and regular 
Groups as the mechanisms to target specific groups of contacts. Here are a couple of 
examples of how you can use Smart Groups and regular Groups for targeting during your 
campaign: 

• You can use Smart Groups to identify contacts you want to target based on specific 
criteria, such as voter demographics, issue interests, primary language spoken, etc. 

• You can track voter demographics about your contacts using the custom data group 
called Voter Info 

• You can use Groups to identify contacts who subscribe to a particular newsletter or 
issue to do an email blast about your campaign. 

• You can then use these Smart Groups and regular Groups to generate your walk list or 
phone bank list. 

Learn more about working with Smart Groups and regular Groups in the "Tags and Groups" 
chapter of this book. 

Preparing a Campaign Event 

To prepare a campaign event in CiviCRM, there are several setup items you may want to 
consider: 



205 



• Define a specific Campaign Source Code for your event. This Campaign Source Code will 
be used for the event and the activity which holds the individual responses gathered 
during the door knock canvass or phone bank campaign. 

• When you set up your event with the Event Type set to "Campaign" you can record 
the questions being asked during the campaign in the Event Campaign Details area. 

• Decide how you want to identify participants in the campaign event. Maybe you only 
want to identify the staff and volunteers who will be involved in conducting the door 
knock canvass or phone bank. Maybe you'll want to add the targeted contacts as 
participants. Activities will be used to record the responses of each individual contacted 
during the campaign as well as the campaign source code related to the campaign, so it 
may not be necessary to add these contacts to the event. In either case, it is 
recommended to also record the Campaign Source Code in the participant's record in 
the Participant Info area. 

• When capturing responses from each individual during the campaign, consider how you 
plan on getting the data back into CiviCRM. If the plan is to enter data one contact at a 
time, which may make sense for phone banking, you will need to record the response in 
the individual's activity record, with the Activity Type of "Door Knock" or "Phone" in 
the Walk List Responses or Call List Responses area. But if you plan on entering 
batches of data at a time, then you will need to plan to import the responses using the 
Import Activities function. 

Working with Voter History 

When using CiviEngage, plan how you will manage voter history and other voter information 
collected during a voter engagement or electoral cycle. Many organizations have access to a 
voter file from which they manage all their voter engagement work outside of CiviCRM. Once 
the voter engagement or electoral campaign is over and voter information is updated with 
who voted and other demographics, organizations most often will only want to keep 
information on the actual contacts they made during the campaign. In this case, only those 
selected records from the voter file and additional voter information, such as responses to 
specific electoral campaign questions, will be imported and maintained in CiviCRM. These voter 
records then become contacts that organizers will continue to engage and target with base- 
building efforts. 

If you wish to collect voter contacts with their demographics, history, and additional 
information, first import voter contacts (with their contact information and demographics) into 
the Voter Info custom group. Then import additional information as Activities, such as 
responses to electoral campaign canvass questions. 

MOBILIZING INDIVIDUALS TO ATTEND AN EVENT 

The Participant Info custom data group that comes with CiviEngage contains fields that hold 
information about prospective event participants, including a history of interactions between 
your organization and prospective participants. Use this information (such as needs for 
childcare or rides) to bring these individuals to your events. Tracking the history of your 
organization's contact with individuals around events such as an annual membership meeting, 
a direct action, or leadership training can help you to understand the effectiveness of your 
outreach methods and determine how committed or engaged an individual is based on if the 
individual actually attends events after multiple contacts. 

This feature is mostly useful for organizers or staff who have a list of individuals they are 
recruiting to attend an event through multiple phone calls or face-to-face meetings. The 
following CiviCRM tasks could be used to mobilize individuals: 



206 



1. Conduct a basic or advanced search or use Groups and Smart Groups to create a list of 
the contacts you want to mobilize or invite to the event. 

2. From the search results or Group Contacts screen, you can add the list of contacts to 
the event by selecting Add Contacts to Events from the Actions list. To find out more 
about how to add contacts to events, refer to the Managing Participants chapter in the 
Events section in this book. 

3. Once you add the contacts to the event, you can enter participant information or 
responses from multiple interactions in the Participant Info area in a contact's 
participant record. You can either enter information for one participant by editing the 
participant record itself, or you can add information for a list of participants at one time. 
For example, if you plan to call through your list by viewing the participant list from the 
event listing, you could use Batch Update Participants Via Profile and select one of 
the following custom profiles provided by CiviEngage: 

• Update Event Invite Responses - to record responses from multiple contacts with the 
participant. 

• Update Participant Info - to record general information about participants, such as if 
they need childcare or rides to the event. 

TRACKING FUNDERS AND FOUNDATIONS 

You can track information about and due dates for grant proposals, letters of inquiries, and 
reports for funders by adding an activity related to the funder's contact record and choosing 
from the Proposal, Letter of Inquiry, or Report activity types. 

You can also tailor information about an individual funder, such as their funding areas and 
issue interests, using the Funder Info custom group. In order to view the Funder Info tab, you 
will need to use the Individual sub-contact type, Funder, when you create a new contact that 
is identified as a funder. 

You can tailor information about a foundation (organization record), such as their program 
areas for funding, using the Grant Info custom group. 

TRACKING MEDIA CONTACTS 

As part of civic engagement and community organizing work, it can be useful to track 
information about your media contacts in CiviCRM, especially if you want to know which media 
contacts or outlets are interested in your organization's issues, or have written articles about 
your work, or for identifying who to contact when you want to publicize the work the 
organization is undertaking. 

You can tailor information about an individual media contact, such as their media type (e.g., 
TV, Newspaper, Photographer, etc.), issue interests and beat using the Media Info - Ind 
custom group. Use the Individual sub-contact type, Media Contact, when you create a new 
contact for a media contact. You can then view and edit the Media Info - Ind tab. 

You can also tailor information about a media outlet (organization) such as their media type 
(e.g., TV, Newspaper, Magazine, etc.) using the Media Info - Org custom group. As with the 
individual media person, use the Organization sub-contact type, Media Outlet, when you 
create a new contact for a media outlet. You can then view and edit the Media Info - Org 
tab. 

TRACKING ELECTED OFFICIALS 

Identifying and collecting information about your elected officials could be useful for your 
community organizing and civic engagement work. You may want to know who is an elected 
official in a specific district, or who to contact on their staff, such as the scheduler, or 
spokesperson. 
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You can tailor information about an individual elected official, such as their elected position 
(e.g., city council, Senate, etc.) and their role using the Elected Info custom group. Use the 
Individual sub-contact type, Elected Official, when you create a new contact for an elected 
official. You can then view and edit the Elected Info tab. Remember that staffers, schedulers, 
or spokespeople for an elected official can be entered as the Elected Official subtype. 

REPORTING AND ANALYSIS 

There are two reports packaged with CiviEngage: Walk List and Phonebank List. In addition, 
the Activity Report is enhanced to filter custom activity fields such as those associated with 
the custom group Call List Responses and Walk List Responses. 

The Walk List report allows you to view, print, or export an individual's contact information 
and demographics such as Member Type, Sex, Age, Party Registration, Voter history, along 
with response codes and notes where a volunteer can collect responses during a door knock 
canvass. 

The Phonebank List report is similar to the Walk List report except that this report is used 
exclusively during a phonebank and contain response codes pertaining to phone responses. 

The Walk List and Phonebank List reports are used to collect information during a campaign to 
later be imported or batch entered back into CiviCRM. 

The Activity Report is enhanced to allow you to search, view, print, or export for specific 
responses from a door knock canvass or phonebank campaign. Use this report not only to 
analyze the effectiveness of your campaign (e.g., how many people you contacted and 
collected responses from) but also to analyze responses from your constituency around an 
issue, or to determine whether individuals may become more involved with your 
organization. 

Disabling vs. Deleting Custom Data 

If you decide you don't need to use or view particular custom groups, fields, or values, we 
strongly recommend that you disable the group, field, or value rather than delete them. The 
Walk List and Phonebank List reports rely on these fields, so deleting certain custom data 
could potentially "break" the reports. 
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47. 



INSTALLATION 



CiviEngage is developed as a Drupal module. Therefore, it will need to be installed and enabled. 
This requires placing the module in the proper directory. Because we need to run a script that 
adds information to the database, we need the added security of a site key. And finally, the 
new subtypes need to be created manually. 

INSTALLING AND ENABLING 

1. You need to checkout civicrm_engage module from CiviCRM subversion repository 

svn checkout http://svn. civicrm . org/ tools /branches /v3 . 1/ drupal /modules /civi 

2. Copy civicrm_engage folder in the /sites/all/modules directory. 

3. Set OR verify your CiviCRM SITE_KEY value in civicrm. settings. php. 

define ( ' CIVICRM_SITE_KEY ' , ' yoursitekeyvalue ' ) ; 

4. Import custom data in CiviCRM specific to CiviEngage using the following URL: 

http : //<website_url>/ sites / all /modules /civicrm/bin/migrate /import . php?name- 

5. Navigate to the Drupal Administer menu -> Site Building -> Modules and enable the 
CiviEngage module. Click Save. 

6. Navigate to the CiviCRM Administer menu -> Configure -> Global Settings -> Address 
Settings and enable Street Address Parsing by checking that box in Address Editing 
section. This feature allows you to automatically parses addresses during contact 
import. 

7. Navigate to the CiviCRM Administer menu -> Configure -> Global Settings -> Search 
Settings -> Autocomplete Contact Search. Uncheck Email and check Phone Number. This 
makes the phone number available for batch update screen and contact autocomplete 
widgets. 

8. Create three new subtypes for Individual Contacts: Media Contact, Elected Official 
and Funder. 

9. Create one new subtype for Organizations: Media Outlet 
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CONFIGURATION 

You will need to configure both Drupal and CiviEngage to use the module. 

CONFIGURING CIVICRM FOR CIVIENGAGE 

CiviEngage can be configured using the following CiviCRM core features: 
Custom Data Groups 

Configure custom data groups and fields to track voter demographics, issue interests, 
leadership levels, volunteer interests, and information about funders, media contacts, and 
elected officials. 

Contact Subtypes 

CiviEngage takes advantage of CiviCRM contact subtypes to expose custom data groups 
associated only with specific subtypes. The following are new contact subtypes: 

Individual subtypes: 

• Media Contact - will expose a contact tab containing information specific to media 
contacts, such as their media type (e.g. Newspaper, Radio, TV, etc.), their "Beat," and 
the media issue interests 

• Elected Official - will expose a contact tab containing information specific to elected 
officials, such as their elected level (e.g. City Council, Senate, etc.) and the role (e.g. 
scheduler, spokesperson, etc.) 

• Funder - will expose a contact tab containing information specific to funders, such as 
their program areas and their issue interests. 

Organization subtypes: 

• Media Outlet - will expose a contact tab containing information about their type of 
media, such as TV, Radio, Wire, Newspaper, Magazine, etc. 

Campaign Source Codes 

CiviEngage uses Campaign Source Codes that you can tailor to describe and track related 
activities, events, event participants, contributions, or memberships. Campaign Source Codes 
can be used to describe a group of related activities, events, contributions, or memberships 
for a specific campaign, project, or program. 

Note: A "Campaign" does not necessarily mean a formal campaign, but can also generally be 
defined as a specific project, program, or organizing activity. 

Door Knock Canvass and Phone Bank Tracking 

• Events used for Door Knock Canvass or Phone Bank - Use the Campaign Event Type to 
expose Event custom fields that allows you to store up to four specific questions being 
asked during a door knock canvass or phone bank. 

• Activities used to Collect Responses from Door Knock Canvass or Phone Bank 
Campaigns - Use the Door Knock and Phone Call Activity Types to expose custom 
fields where you can collect an individual's responses during a door knock canvass or 
phone bank. 

Reports 
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• Walk List Report - view, print or export certain demographic and other constituent 
information in a specific geographic area to collect responses to be used during a door 
knock canvass. The Walk List Report takes advantage of the optional address parsing 
feature to build the report. 

• Call List Report - view, print or export certain demographic and other constituent 
information along with an area to collect responses to be used during a phone bank. 

• Activity Report - includes filters for activity custom fields so that you can build a report 
of specific activities based on criteria about your constituency, such as creating a report 
to analyze particular responses from a door knock canvass or phone bank. 

Grant Proposal and Report Tracking 

CiviEngage uses the Proposal, Letter of Inquiry and Report Activity Types to expose custom 
fields to track information and schedules for proposals, letters of inquiries and reports related 
to an individual funder or foundation. 

Custom Profiles 

CiviEngage configures several custom profiles for easier batch updating of individual or 
organization information, such as voter demographics, issue interests, volunteer interests, or 
event participant information. To learn more about profiles, please refer to the "Profiles" 
section of the book. 

CONFIGURING CIVIENGAGE 

When you install CiviEngage a number of custom fields are automatically created. These fields 
are designed to support your community organizing work. Most of these fields are multiple 
choice fields which have been pre-populated with sample options. Before you start using 
CiviEngage, you need to review and modify the supplied options to meet your needs. 

Begin by going to Administer -> Customize -> Custom Data in the navigation menu. In the 
following list bolded items are Group Header entries in the Custom Data screen. The bulleted 
items are custom fields under those Group Headers that have been added by CiviEngage; the 
other fields under these group headers are standard to CiviCRM. The choices for these custom 
fields should be edited before you use CiviEngage. You should add, delete, or edit the available 
options for each custom field to make them better fit your organization's needs. 

Communications Details 

• Best Time to Contact 

Voter Info 

All of the fields in this custom data group are added by CiviEngage, so you should review and 
edit them all to suit your needs. You may also want to add specific local voter fields that apply 
to you. 

Constituent Info - Individuals 

• Constituent Type 

• Staff Responsible - note that the values for this field are also used for Event Contact 
Person. Replace the sample names in the list with your staff, member or volunteer 
coordinators, and other folks that have individuals assigned to them. 

• How Started - edit this list to fit the ways in which members are brought into your 
organization. 

Grassroots Info 
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• Member Status - three status choices included by default. Think about other member 
statuses that might work for your organization and add or remove as needed. 

• Leadership Level - The default options for tracking an individual's leadership level within 
your organization are 1-5. Change this to match however your organization tracks this 
information. 

• Issue Interest - this custom field uses the same set of options as the Funding Areas and 
Funder Issue Interest fields. It is a list of issues that your organization works on or 
tracks. 

• Volunteer Interests - a list of volunteer activities that your members can take on. 

Constituent Info - Organizations 

• Constituent Type - Org 
Grant Info 

• Funding Areas - this custom field uses the same set of options for Issue Interest and 
Funder Issue Interest. 

Participant Info 

• Participant Campaign Code - this custom field uses the same set of options as the 
Contribution Campaign Code, Event Campaign Code, Activity Campaign Code and 
Membership Source Code fields. Delete the example campaigns and add your own. This 
is the mechanism CiviEngage uses to connect a contact's participation across all these 
different actions. For example, a Campaign called "House Party 10-1-2010" could have an 
Event tied to it, a participant of that Event tied to it, an activity when an organizer calls 
a contact inviting them to attend an Event, a membership entry when they become 
members at the Event and a contribution when they pay their dues. 

Contribution Source 

• Contribution Campaign Code - see Participant Campaign Code. 

• Contribution Campaign Method - this custom field uses the same set of options as 
Membership Source Campaign. Add different types of interactions or locations where 
you would be engaging potential members and donors. 

Event Details 

• Event Contact Person - also used for Staff Responsible. Add all appropriate people to 
this list. 

• Event Campaign Code - see Participant Campaign Code. 

Activity Source Details 

• Activity Campaign Code - see Participant Campaign Code. 

Organizational Details 

This custom group is used to store information that is specific to organizations. There is only 
one example currently. 

• Rating - if you need to evaluate organizations in some way, change the options to reflect 
that. 

Demographics 
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• Ethnicity 

• Primary Language - this custom field uses the same set of options as Secondary 
Language. Only one entry can be selected for each contact for this field. 

• Secondary Language - also used for Primary Language, but as many choices as needed 
can be checked. 

Media Info - Org 

This custom group is only applicable to the New Media Outlet contact subtype. 

• Media Type - Org - this custom field uses the same set of options as Media Type - Ind: 
TV, Radio, Wire, Newspaper, Magazine 

Media Info - Ind 

This custom group is only applicable to the New Media Contact contact subtype. 

• Media Type - Ind - this custom field uses the same set of options as Media Type - Org 

• Beat - this refers to the general category of topics that a media contact covers, such as 
local government, education, neighborhoods, religion, labor, etc. 

• Media Issue Interest - uses the same option list as Issue Interest. As you come to know 
a reporter, you will learn the issues they are particularly interested in, even if it differs 
from their assigned beat. 

Elected Info 

This custom group is only applicable to the New Elected Official contact subtype. 

• Elected Level - the governmental body the individual is part of (City Council, state 
legislature, mayor, etc.) 

• Role - Whether the contact is the elected official, or the official's staff, spokesperson, 
etc. 

Funder Info 

This custom group is only applicable to the New Funder contact subtype. 

• Funder Issue Interest - this custom field uses the same set of options as Issue Interest 
and Funding Areas. 

Membership Source Details 

• Membership Source Code - Uses the same codes as the Participant Campaign Code and 
Contribution Campaign Code. 

• Membership Source Campaign - also used for contributions. Add different types of 
interactions or locations where you would be engaging potential members and donors. 
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ESSENTIAL TASKS 

This chapter provides instructions on how to do some of the common tasks associated with 
the CiviEngage module. 

PRINTING A WALK LIST 

CiviEngage offers a report that allows you to easily print walk lists for folks who are doing 
canvassing, Get Out the Vote (GOTV) or other door knocking activities. 

1. If you want to use Groups or Smart Groups to develop your walk list, be sure to create 
the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the walk list report. Choose whether you want the Country or Email field to 
display. 

4. Scroll down to the "Set Filters" section. You must select a filter to obtain results. All 
your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the report results, but if you click on "Print Preview" you will see your walk list. 
You can use your browser's Print Preview feature to see the walk list on a per-page 
basis. 

PRINTING A PHONE LIST 

CiviEngage offers a report that allows you to easily print phone lists for folks who are doing 
phone banks or other mass phoning activities. 

1. If you want to use Groups or Smart Groups to develop your phone list, be sure to 
create the groups you want. 

2. Click on Reports -> Create Reports from Templates in the navigation menu. 

3. Click on the phone list report. Choose the columns you want to display from the 
template screen. 

4. Scroll down to the "Set Filters" section. You must select a filter in order to obtain 
results. All your Groups and Smart Groups appear in the Group filter. 

5. Once you have set your filter(s), scroll down and click on "Preview Report." You are now 
seeing the results but if you click on "Print Preview" you will see your phone list. You can 
now use your browser's Print Preview feature to see the phone list on a per-page basis. 

CREATE A CAMPAIGN SOURCE CODE 

In order to use CiviEngage effectively, you need to create "campaigns" that you connect all 
your activities to. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Participant Info in the list and click the corresponding "View and Edit Custom Fields" 
link. This gives you a list of Custom Fields. 

3. Find Participant Campaign Code and click the "Edit Multiple Choice Options" link. Now you 
are seeing a list of the interests. 

4. Scroll down and click on "New Option" and add your new campaign. 

Please note that this new campaign code will now be available for Event, Membership and 
Contribution Campaign Codes as well as in the Participant Campaign Code that it was just 
created in. 

ADD AN ISSUE INTEREST 



214 



To better understand and track the areas that your members and constituencies are 
interested in working on, CiviEngage provides a field that collects this information. Customize 
this list to meet the needs of your particular organization. 

1. Click on Administer -> Customize -> Custom Data . 

2. Find Grassroots Info in the list and click on the corresponding "View and Edit Custom 
Fields" link. This gives you a list of Custom Fields. 

3. Find Issue Interest and click the "Edit Multiple Choice Options" link. Now you are seeing a 
list of the interests. 

4. Scroll down and click "New Option" and add your new interest. 

Please note that this new issue will also appear in Funding Areas and Funder Issue Interest as 
well as in the Issue Interest that it was just created in. 

TRACK WALK LIST/CALL LIST RESPONSES 

Responses to the questions your canvassers or phone bankers ask are tracked in an 
individual's activity record. The text of the questions are tracked in the event record. In order 
to properly configure this, start with creating the event. 

1. Click on Events -> New Event. 

2. Choose Campaign for your Event Type, which will let you see the Event Campaign Details 
section. 

3. Scroll down to the Event Campaign Details section and add the text to the questions for 
this particular campaign. 

4. You will also want to add an Event Campaign Code, which is in the Event Details section. 

Next you would go to a contact record to create a "Door Knock" or "Phone Call" activity and 
finish configuring this functionality. 

1. Go to a contact's record and click on "new activity." 

2. Choose "Phone Call" or "Door Knock" and you will get the Activities screen. 

3. Scroll down and click on the Call List Responses section. 

4. Now you can record the responses. 

5. You then add the Activity Campaign Code in the Activity Source Details section. Make 
sure you choose the same campaign as you did for the Event. 
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PRINT AN ACTIVITY REPORT 

One of the features of CiviEngage is the ability to track the different activities that your 
members are engaged in. Use the activity report to better understand what your members 
are doing. 
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1. Click on Reports -> Create Reports from Template . 

2. Choose the Activity Report. This brings up the Activity Report Template. You are now 
looking at all the options available for printing a report based on the activities CiviEngage 
offers that your contacts are engaged in. 

3. The first section lists the columns that are available for your report. Use the check 
boxes to decide what information you want your report to show. The default values are 
Assignee Contact Name , Target Contact Name , Activity Type , Subject, Activity Date and 
Activity Status . You can choose columns from Walk List Responses, Leadership Level 
(from Activities), Call List Responses, Proposal Info or Activity Source Details. 

If, for example, you want a report of Walk List Responses from a specific campaign, you 
would check boxes from the Walk List Responses section and choose the Activity 
Campaign Code from the Activity Source Details section. Please note that the default 
value for Activity Date is "this month." If you want a different range of dates you have 
many options. Click on "this month" and you will see all the options available. Included is 
Date Range, where you can choose a specific range of dates. 

4. The next section allows you to group your data by the Source Contact (the default 
value), Activity Date or Activity Type . Check the appropriate box for your report. 

5. The final section is for filtering your data. Here you can choose data from any of the 
activity fields that CiviEngage offers. 

To continue our example, you might choose to include data where the first two Walk 
List questions were answered yes. Choose Y in the appropriate boxes and scroll down to 
the Activity Source Detail section and choose the appropriate Activity Campaign Code . 
Click Preview Report and view your results. 

6. Once you have your results, you have a number of options. You can "Preview" the 
report, "Preview" the PDF of the report, "Preview" the CSV (export your report into a 
spreadsheet), or "Add the contacts to a group." 

SEARCH FOR ACTIVITIES 

The are a number of ways to search for the activities that you create using CiviEngage: 

• Run a report, as explained above 

• Use the Find Activities search option 

• Use the CiviCRM Advanced Search 

• Run an Activity Search, which is in Custom Searches. 

Using the Find Activities search option 

1. Click on Search -> Find Activities . 

2. You are presented with a number of search criteria options. You can enter the name or 
email address of a contact in the database. You can choose one or more activity types. 
You can add a range of dates during which activities happened. You can search for 
contacts in specific Activity Roles: With, Created By and Assigned to. You can look for 
specific subjects, test activities or by the status of the activity. Each criterion you select 
will narrow your search results. 

3. Click Search and you will get to the Search Results screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using Advanced Search to find Activities 
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1. Click on Search -> Find Contacts - Advanced Search . 

2. Scroll down to the Activities section and click on it. Here you find all the options available 
in CiviEngage for activities. 

3. Once you choose your search options and click Search you will get to the Search Results 
screen. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 

Using the Custom Search: Activity Search 

1. Click on Search -> Custom Searches... -> Activity Search . 

2. You are presented with different criteria by which you can search for information. Enter 
your search terms and click Search. 

3. The Search Results provides the Name of the person, the Status, Type and Subject of 
the Activity and who assigned the activity. You also have a button for viewing and 
editing each activity record. 

4. Select some or all of the search results and click on "- actions." 

5. You can then choose to export your results, send an email to all the contacts you found 
or add these contacts to a group or smart group, among other options. 
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EXTENDING CIVICRM 



This section contains developer documentation for CiviCRM. It should be useful for developers 
wishing to extend CiviCRM and also for organizations who want to ensure that their developers 
are using best practices to extend CiviCRM. 

There are many different ways you can extend and customize CiviCRM, and this section takes 
you through them in order of simplest to most difficult. If you find that you cannot do 
something you're trying to do using the tools and techniques outlined in this section, please get 
in touch with the CiviCRM developers in the forums (http://forum.civicrm.org/) or on the IRC 
channel (#civicrm on irc.freenode.net) and let them know. Hacking on the core code should 
always be a last resort and done in consultation with the core team who will always be happy 
to help you find the best way to cover your use case. 

WHEN DO YOU NEED TO CODE? 

There are a lot of different options to customize CiviCRM to fit your specific needs. They are 
listed roughly in order of complexity: 

1. Change the configuration: (ok, this isn't coding but it is worth repeating) you can use 
custom fields, profiles, components and many existing Drupal modules andjoomla! 
extensions to customize CiviCRM without writing a line of code. This book covers many 
of these options in other sections, so make sure you've exhausted all of those 
possibilities before you dive into extending the code. 

2. Edit CSS: You can create a new Cascading Style Sheet (CSS) file and use it, for example, 
to adapt the style to your site or hide elements that don't make sense in your 
environment. Administer -> Configuration -> Global settings -> Resource URLs field 
"Custom CiviCRM CSS URL". 

3. Edit the templates: Useful to change the layout of forms, and to add more data or 
features via AJAX. Read about templating and APIs to know more. 

4. Implement hooks: Hooks are called at specific points in the code as users interact with 
CiviCRM and are useful, for example, when you want to change the default behavior 
when you create, update or delete an entity, create a new custom mail merge token, or 
to populate a custom field automatically based on your own business logic. 

5. Add custom searches or reports: Use these to fetch information and display it in a 
unique way. 

6. Extend your CMS: Create a Drupal module or Joomla! extension that integrates with 
CiviCRM. 

7. Override PHP files: In the same way that you can override templates, you can override 
any file in CiviCRM. If you have to modify core, it's much better to override files than to 
edit them. 

8. Write a new CiviCRM component or patch CiviCRM: Regardless of which path you 
take to extending and customizing CiviCRM, chances are that someone else would be 
interested in what you did. Share it with the community! If others start using your 
contribution, you're likely to get bug fixes, improvements, and documentation as a 
bonus. Let us know what you did in the forums or IRC channel (see above). 

Where possible use the documented APIs in your extensions, this will make them less likely to 
break when you upgrade CiviCRM. 

Before venturing into any development, we strongly suggest that you discuss what you want 
to do, and how you want to do it, with the community. We will help you find the simplest way 
to reach your goal and may be able to point you to others doing similar work. 

Please consider using the Academic Free License to open more opportunities to share your 
work. This also makes contributing your work back to the CiviCRM project very simple. 
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DEVELOPING PAGE TEMPLATES 



CiviCRM uses page template files to display all the pages. This makes it possible for a person 
to customize any CiviCRM screen to suit a special requirement or preference. The HTML for 
CiviCRM pages is not embedded in PHP code, instead a template engine (Smarty) sends the 
correct page to the web browser. 

!A person should be familiar with HTML and CSS syntax to be comfortable editing page 
templates. Some page templates additionally make use of JavaScript and an Ajax utility, 
JQuery. 

CHANGING PAGE TEMPLATES IS THE WRONG CHOICE 
WHEN ... 

If it is possible to make the needed changes by updating the CSS styles. For example, if 
a requirement is to hide or move some information or form fields on a screen, a CSS style for 
that HTML element can be changed to display: none, or position: absolute within the CSS file. 

If there is a CiviCRM hook available that can control the page. For example, there is a 
hook that can modify the information on the Contact Summary screen. 

If there is no process in place to update the page templates after an upgrade to a new 
version of CiviCRM. Page templates are stored in a separate folder and are not touched 
during an upgrade, However new versions of CiviCRM often change which placeholder elements 
are available in various templates. Proper source control procedures are needed to simplify 
upgrades to new versions. 

SMARTY TEMPLATES INTRODUCTION 

CiviCRM uses a page template engine called Smarty. This documentation is focused on how 
Smarty is used within the CiviCRM environment. Every Smarty element is enclosed between 
braces like these: "{}". All the other text is going to be displayed directly as HTML in the 
rendered page. 

Each page template is stored in a file with the extension .tpl. The PHP code assigns variables 
for content that needs to be displayed, and then lets the template engine take care of 
presenting it. 

The Smarty template engine always does this process : 

1. Load the contents of a .tpl file. 

2. Scan the .tpl file for placeholder elements. 

3. Replace each placeholder element with the corresponding variable value. 

4. Send the resulting HTML to the web browser. 

These are the most commonly used Smarty template elements: 
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• {$Name}: To display the value of a variable named "Name" 

• {$row.Name}: To display the value of the attribute Name in the object Row 

• {foreach from=$rows item=row}...{/foreach}: To loop though all the items of the Rows 
array 

• {literal} JavaScript code{/literal}: To indicate to Smarty the "{}" aren't smarty elements 
but JavaScript code, enclose JavaScript between {literal} 

• {Idelim}... {rdelim}: is generating "{}". Useful if you have a simple JavaScript code that 
needs a lot of values from Smarty variables 

• {include file="CRM/path/to/template.tpl" param1=xxx}: includes the result of the 
template.tpl. Some included files expect to have extra param (e.g., paramT). 

Please read the Smarty documentation for more information. 

Tip: To see what variables have been assigned to the template, enable debug (Administer -> 
Configure -> Global Settings -> Debugging) and on any URL, add &smartyDebug=1. It opens a 
new browser window listing all the variables and values. 

CiviCRM introduces some extra features to Smarty: 

• {ts}Any text{/ts}: It will display the translated text (if you don't use US English) 

• {crmURL p='civicrm/contact/view' q="reset=1&cid= N $row.source_contact_id N "}. 
Generates the proper CiviCRM URL that works both onjoomla! and Drupal. 

• {crmAPI} Allows retrieval and display of extra data that is not assigned to the template 
already. Read about the CiviCRM API for more information. 

HOW TO FIND AND MODIFY THE TEMPLATES ? 

All the templates are under the folder templates/CRM in your CiviCRM installation. Finding which 
template is used on a given page can be difficult, but the easiest way to find out the answer is 
to view the source of the page from a web browser and search for ".tpl". For example, for the 
Contact Summary page, use the web browser to open the Contact Summary page, then click 
"View Source" in the browser. You should find an HTML comment such as: 

<!-- .tpl file invoked: CRM/Contact/Page/View/Summary . tpl . Call via form. tpl if 

You can then view the file at templates/CRM/Contact/Page/View/Summary.tpl to see how the 
HTML is generated. If you want to modify the layout; for instance to reorder the content, do 
not modify directly these files, as all the modifications will be lost on the next upgrade of 
CiviCRM. The proper way is to create a new folder outside of your CiviCRM folder, then 
navigate to "Administer -> Configure -> Global settings -> Directories" in the navigation menu, 
and set the complete path of the folder that is going to contain your custom templates in the 
field Custom Templates. 

SCENARIO: THE CONTACT SUMMARY SCREEN NEEDS TO 
BE CHANGED 

If you want to alter the Contact Summary page template for Acme organization, perform 
these steps: 

1. Create the folder /var/www/civi.custom/acme/templates/CRM/Contact/Page/View 

2. Update the Custom Template field in the Global Settings directories to 
/var/www/civi.custom/acme/templates. You can use any directory. We found it easier to 
put the custom templates under /var/www/civi.custom/yourorganisation. 

3. copy templates/Contact/Page/View/Summary. tpl from your CiviCRM install to 
/var/www/civi. custom/acme 
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Tip: Say you want to modify the template for a specific profile form, or a specific event. 
Instead of copying the Form template to its default place (templates/CRM/Profile/Form/Edit.tpl), 
you can create a subfolder with the ID of the profile and put the template file you want to 
change in the subfolder {templates/CRM/Profile/Form/42/Edit.tpl to modify only the form for 
ProfilelD 42). 

You might be willing to modify a template that isn't directly the page you load, but added later 
via Ajax. For instance, perhaps you want to change all the tabs beside the Content Summary 
(Activities, Groups, etc.). The easiest way to do this is to install a development oriented plug-in 
to your web browser. If using Mozilla Firefox, the Firebug plug-in is indispensable. Open the 
Firebug console (or equivalent in your browser) and click the tab. You will see what URL has 
been loaded for the tab (e.g., for the notes tab: http://example.org/civicrm/contact/view/note? 
reset=1&snippet=i&cid=1). Open it in a new window or new tab of the web browser, and view 
the source. It also contains a comment identifying the template used 
(CRM/Contact/Page/View/Note.tpl). 

Keep in mind that when you modify a template, you might have a template that doesn't work 
properly anymore after an upgrade of CiviCRM, because the layout has changed or the name 
of variables assigned to the template was modified. In our experience, the easiest is to use a 
source code management system (SCM) to keep track of the changes you have made. Before 
doing any modification of the template you copied, add it to your SCM, and obviously also 
commit the template after having modified it. That way, you can easily generate a patch of 
your changes, and see how to apply them to the latest version of the template. 

SEMANTICALLY MEANINGFUL HTML ATTRIBUTES 

To make it as easy as possible for you to style any element in the page (e.g. put a yellow 
background on all the contacts of the subtype "members"), or add Ajax (clicking on the status 
of the activity changes it to complete), we strive to have a consistent and coherent schema 
for class names and ids for the generated HTML. This makes it easier to isolate the elements 
you want to alter from a custom style or from JavaScript: 

• There is a class crm-entityName defining the type of the entity bubbled up as high as 
possible in the DOM. For instance, each line on a list of activity has <tr class="crm- 
activity ..."> 

• There is an id crm-entityName_entitylD allowing to find the id of the entity bubbled 
up. e.g., on a list of contacts, the contact number 42 has a <tr id="crm-contact_42" ...> 

• Each field or column contains a class identifying it, e.g., "crm-activity-subject" 

• Each field or column that contains a value with a fixed set of possible values (e.g., a 
Status, a Role, a Contact Type) contains a class identifying it. It doesn't contain the 
human readable version (that can be changed), but the id or a name that can't be 
modified by the end-user; such as class="crm-activity-status-id_42". This is on the 
top of the class identifying the field name, so the complete HTML is <td class="crm- 
activity-status crm-activity-status-id_42">Hitchhiked</td>. 

At the time of the writing, some of the templates don't follow these conventions. Please 
update them and submit a bug tracking issue with a patch if you need to use a template that 
isn't yet complying. For more information about submitting a bug or issue, read About the 
CiviCRM community. 

DISPLAYING MORE CONTENT AND ADDING AJAX 
FEATURES 

If your modifications go further than "simple" modifications of the layout, but need to display 
more content than the one assigned to the template by default, or to add Ajax functionality, 
use the CiviCRM API. Please read more information about using the CiviCRM API from Ajax to 
pursue this approach. 
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In most cases, using the CiviCRM APIs should be simple and only takes a few extra lines of 
modifications. 

SOME USEFUL VARIABLES AND EXAMPLES 

On each page template, you have extra Smarty variables populated by CiviCRM. 

{$config} Contains a lot of useful information about your environment (including the URL, if 
it's Drupal or Joomlal, etc.) 

{$session} Contains information about the user. 

If you want to modify the template only for a logged-in user but leave it identical for 
anonymous users, do the following: 

{if $session->get ( ' userlD ' ) > 0} 

Insert your modifications here 
{/if} 
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52. 



WRITING CUSTOM REPORTS 



This chapter is a brief introduction to creating a new report in the CiviReport system. You can 
use the same programming techniques to extend an existing report template. These tasks call 
for a strong grasp of PHP. More details are available in the wiki page on customizing reports: 
http://wiki.civicrm.org/confluence/display/CRMDOC/CiviReport+structure+and+customization . 

CREATING OR CHANGING A REPORT TEMPLATE IS THE 
WRONG CHOICE WHEN ... 

If you want a batch action on an existing result set. CiviReport does not support most of 
the batch actions. If your main purpose is to print or send an email to a list of contacts that 
meet specific criteria, write a custom search. 

REPORT SPECIFICATION 

Before starting on a custom report, fill out the form on the CiviCRM wiki for report 
specifications. Add your specification there and ask for comments in the forum or on IRC. 

CREATING A CUSTOM TEMPLATE 

This section creates a custom report listing all contacts' Display Name, First Name and Last 
Name. Note that we'll be talking about both Smarty templates (.tpl files) and PHP report 
templates—be careful not to confuse the two. 

Replacing an existing report with your own version is not recommended because you may 
need the original too, and because an upgrade of CiviCRM will overwrite your changes with the 
CiviCRM version. In this section, therefore, we'll create a new Smarty template and a new PHP 
template for the report. You can also copy a template and report to a new location and edit 
them to create your custom report. 

All reports are located under CRM/Report/Form/ and grouped by component. 
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1. Create a new Smarty template and a new PHP template for the report. Because this 
example creates a report about contacts, we'll create a new report template named 
Contact. php and a Smarty template named Contact.tpl, both in a custom directory. The 
paths will look like: 

CUSTOM_PATH /CRM/Report /Form/ Con tact /Contact. php 
COSTOM_PArH/templates/CRM/Report/Form/Contact/Contact . tpl 

2. Add a base class named CRM_Report_Form_Contact_Contact in Contact.php, Your 
class must inherit the form class used for the report framework. So Contact.php looks 
like: 

<?php 

require_once ' CRM/Report /Form. php ' ; 

class CRM_Report_Form_Contact_Contact extends CRM_Report_Form { 

J 

3. Your Smarty template file must include the report framework template. Thus, 
Contact.tpl is: 

{include f ±le=" CRM/Report /Form. tpl" } 

4. Register your report template in CiviCRM. Go to: Administer -> CiviReport -> Register 
Report. Enter the details shown in the following screenshot. 

Report Template 

New Report Template 

Title » Contact Report | 

Report title appear in the display screen. 

Description * Provides a list or cor tact first arc last rams 

Report description appear in the display screen. 

URL * contact/contact | 

Report Url must be like "contribute/summary" 



CRM_Report_Form_Coritact_Contact 
Report Class must be present before adding the report here, e.g. l CRM_Report_Form_Contribute_Summary l 



Weight * |29 

Component f Contact t I 



Specify the Report if it is belongs to any component like "CiyiContribute" 



5. In a constructor, create an array to hold a contact, which in turn hold an array 
specifying two fields you want to display. 

function construct ( ) { 

$this->_columns - array ( ' civicrm_contact ' -> 

array ( ' dao ' => ' CRM_Contact_DAO_Contact ' , 
'fields' => 
array ( 'first_name' -> array ( 'tit] 
'last_name' -> array ( 'tit] 
) ) 
) ; 
parent:: construct ( ) ; 
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6. Build the display by issuing a SELECT against the database. You can create column 
headers and fill in each field in the display with the results returned by the SELECT. 



function preProcess ( ) { 

parent : :preProcess ( ); 



// build select query based on display columns selected 
function select ( ) { 

$select = Sthis->_columnHeaders = array ( ); 
foreach ( $this->_columns as $tableName => Stable ) { 
if ( array_key_exists (' fields ' , Stable) ) { 

foreach ( Stable [' fields ' ] as SfieldName => Sfield ) { 
if ( CRM_Utils_Array: lvalue ( 'required', Sfield ) I 
CRM_Utils_Array: rvalue ( SfieldName, Sthis->_params [ ' f ie 
Sselect[] = " {Sfield[ 'dbAlias '] } as { StableName }_{ $ 

// initializing columns as well 
Sthis->_columnHeaders [ " { StableName )_{ SfieldName) " ] [ 

CRM_Utils_Array: rvalue ( 'type', Sfield ) ; 
Sthis->_columnHeaders [ " { StableName )_{ SfieldName) "] [ 



Sthis->_select = "SELECT " . implode! ', ', Sselect 



function from{ ) { 

$this->_from = "FROM civicrm_contact { Sthis->_aliases [ ' civicrm_cont 



7. Your custom report template is ready. Press the Preview button to see the results. 
Contact Heport - Template 
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After you've installed and tested your report, add it to the CiviCRM wiki as a patch to the 
project so that it can be used by others in the community. 
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DEVELOPING CUSTOM SEARCHES 



A custom search is a method of providing new functionality within the standard CiviCRM 
navigation structure. This chapter looks at how to develop a Custom Search and is written for 
programmers. 

Custom searches produce a screen showing a set of contacts, from where you can execute 
actions such as sending email, printing mailing labels, and all the other actions that are 
available for contact search results within CiviCRM. The results page displays the same as any 
other search results page, such as results delivered from an Advanced Search, however, a 
predefined set of functions is controlling which information is delivered to the result page. 

Custom Searches follow the Hollywood principle, "Don't call me, I'll call you." In this case 
CiviCRM calls your functions at the appropriate time. 
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WHEN TO USE CUSTOM SEARCHES 



A custom search is the right choice when ... 
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• you need to access the Actions list after running your search, to send email, add the 
contacts to a group or other actions (since the list of actions and list of tokens can be 
extended with developer-created hooks, the combination of a custom search + custom 
action + custom token is a powerful tool for implementing a special requirement. If you 
are interested in creating new actions or tokens, read the section on CiviCRM hooks in 
the chapter Extending CiviCRM.) 

• you want to create a Smart Group based on the parameters of the custom search 

• you want to use the search results to drive a mass mailing in CiviMail 

• you want results that can be sorted by clicking any column heading in the results page. 

A custom search is the wrong choice when ... 

• you can use the Advanced Search or the Search Builder to create the same results 

• the information you need is not primarily accessible from the CiviCRM database tables 
(for example, the information needs to be retrieved from a third-party system or a 
different database) 

• the information you need does not include the CiviCRM contact ID (for example, 
information related to summarised event income). 

CiviReport is a better choice if ... 

• you need to schedule and send the entire result as an email to one or more people 

• you need a summary/detail drill-down style of results page where the detail is not just 
the contact summary screen 

• you want to use the results as a dashlet on your CiviCRM dashboard 

• you need multiple report break areas within the results page, such as subtotals after 
every 5 records as well as grand totals 

• you need to include information not related to contacts. 

GETTING STARTED CREATING A NEW CUSTOM SEARCH 

In this section we will create a new custom search called "BirthdaySearch" that will find all 
contacts whose birthdays fall in June. 

Custom searches are written using PHP and SQL. Very little knowledge of PHP is needed, as 
you start with a template file and only make minor changes. In many cases the only changes 
are the SQL Select statement and which columns to display in the results. 

Plan and test 

Before writing the code, it is important to plan and test the SQL query and verify the results. 
It is valuable at this stage to review the database tables and test the SQL select statements 
within the database using an SQL tool such as PHPMyAdmin. 

It may be helpful for you to review the information at: 

• Useful CiviCRM SQL Queries: 
http://wiki.civicrm.org/confluence/display/CRMDOC/Useful+SOL+queries 

• CiviCRM Data Architecture: http://wiki.civicrm.Org/confluence/x/GQDEAQ 

• CiviCRM wiki: http://wiki.civicrm.0rg/confluence/x/MYOUAO 

Setting the filepath 

Your custom search files can be stored almost anywhere, but you must tell CiviCRM where 
these files are. 
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1. Within CiviCRM, go to: Administer > Configure > Global Settings > Directories 

2. Fill in the Custom PHP Path Directory. This needs to be an absolute path to your PHP 
directory, such as /home2/jsmith/public_html/civicrm_custom_code/ 

3. Create a copy of an existing custom search file, such as the EventAggregate.php file. 
You will find this file at: 

<joomla 

root>/administra tor/com ponents/com_civicrm/civicrm/CRM/Contact/Form/Search/Custom 

or 

<drupal root>/sites/all/modules/civicrm/CRM/Contact/Form/Search/Custom 

4. Place the EventAggregate.php file in the directory: 
/home2/jsmith/public_html/civicrm_custom_code/CRM/Contact/Form/Search/Custom 

5. Rename the copied EventAggregate.php file to BirthdaySearch.php 

UNDERSTANDING AND UPDATING THE SEARCH CODE 

Start by opening the file BirthdaySearch.php in a text editor. The first change needed is to 
change the class declaration to: 

class CRM_Contact_Form_Search_Custom_UpcomingBirthdays 
implements CRM_Contact_Form_Search_Interf ace { 



Functions you will probably need to modify: 

• function_construct: this controls the columns that are part of the results page. 

• function all: this function is responsible for returning the SQL select statement to 
execute that gets the entire set of information. The select statement MUST include a 
field named "contactjd". Normally it also contains fields named "name" and 
"sort_name". For example: 

if ( SonlylDs ) { 

Sselect - "DISTINCT civicrm_contact . id as contact_id, civicrm_contc 
} else { 
$select = "DISTINCT civicrm_contact . id as contact_id, CONCAT ( monthname 

t 

$from = $this->from( ) ; 

$where = $this->where ( $includeContactIDs ) ; 

$sql = "SELECT $select FROM $from WHERE Swhere " ; 

• function from: this function is responsible for returning the from clause of the SQL 
select statement. It is normally called from the "all" function as well as by CiviCRM. 

• function where: this function is responsible for returning the where clause of the SQL 
select statement. 

• function buildForm: this controls the results title as well as the parameters that are 
available to the person running the search. For this birthday search, you may want the 
user to be able to choose the month. 

Functions you may need to modify: 

• function summary: this function is needed if some or all columns have summary 
information, such as total number of birthdays in June. 

• function alterRow: this function allows you to alter the contents of a piece of 
information before the results are displayed. 
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• templateFile: this function returns the name of the Smarty template that CiviCRM will 
use to present the results. For most purposes, the template 
CRM/Contact/Form/Search/Custom/Sample.tpl will suffice. 

PREPARE TO RUN THE CUSTOM SEARCH 

Before you can run the custom search, CiviCRM needs to be informed that it exists. This is 
accomplished by the following steps: 

1. Go to: Administer > Customize > Manage Custom Searches. 

2. Scroll to the bottom of the page and click the button New Custom Search. 

3. Provide the class path as: CRM_Contact_Form_Search_Custom_BirthdaySearch 

4. Provide the title as: Birthday Search 

The new Birthday Search should now appear in (and can be run from) the list of custom 
searches in the navigation menu. It will also appear on the page reached by going to Search > 
Custom Searches. 

The new custom search will not appear in the black navigation menu unless the navigation 
menu is edited. This can be done by going to Administer > Customize > Navigation Menu. 

TESTING THE CUSTOM SEARCH 

Always test the following behaviors of the new search: 

• Test for a variety of form values, especially for invalid data. Errors in validation can lead 
to serious security breaches. Just because there is a drop-down list of valid months, do 
not assume that only valid months are passed to your custom search. Also test for 
values with apostrophes and other special characters. 

• Test the previous and next page links for a variety of different size results. 

• Test the first/last page links for a variety of different size results. 

• Make a Smart Group from it and send a CiviMailing to that group. 

• Test other actions in the Action menu such as Send an Email, or create PDF letters with 
mail merge tokens. 
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54. 



WORKING WITH THE API 



CiviCRM provides an Application Programming Interface (API). This is a stable, coherent and 
standardised set of functions and it is the recommended way for any external programme to 
interact with CiviCRM. 

CiviCRM is open source software, which means you can modify the source code or call 
methods and objects directly. But if you did, you would probably encounter difficulties when 
upgrading to a new version of CiviCRM because those methods and objects may have changed 
in the new version. 

On the other hand, the API is designed to remain the same so it should behave identically 
across versions, or at the very least warn developers well in advance of a change. An API 
change between minor versions will be considered a regression bug and you should report it to 
the CiviCRM development team so they can fix it. 

Most of the API functions are low level methods that allow you to interact with one of the 
entities in CiviCRM (contact, tag, group, activity, etc.). For each entity type, there are at least 
3 actions: add (handles add and update), get (one specific entity), and delete. Some entities 
work slightly differently. Read the API docs in the wiki for the most up-to-date 
information: http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM-l-Public-l-APIs 

Additionally, the API test directory http://svn.civicrm.org/civicrm/trunk/tests/phpunit/api/v2/ 
contains examples of most of the APIs, along with what parameters to use as input and what 
return parameters to expect. 

There is an ongoing effort to better standardise the APIs, and help is certainly appreciated. If 
you're interested in lending a hand, post to the API section of the developer forum here: 
http://forum.civicrm.org/ 

HOW TO USE THE API 

The naming convention for API functions is civicrm_entityname_action. For instance, the 
function to create a contact is civicrm_contact_add, and the method to delete a group is 
civicrm_group_delete. 

Every API function takes one single array of parameters as input. If the function needs a single 
parameter (e.g. the identifier of the group you want to delete), this will be an array containing 
a single item like so: array( 'id' => XX ); 

Every API function returns a single array. All the delete and add/modify functions contain an 
item "is_error". If the function couldn't delete or modify the entity as you requested, is_error 
= 1 and a second item error_message returns details about the error (eg. "DB Error: already 
exists"). If you have turned on debugging (see the Developer Tips & Tricks section), you have 
an extra item "debugjnfo" that contains a more detailed explanation (e.g. " INSERT INTO 
civicrm_tag (name) VALUES ('existing tag name 1 ) [nativecode=1062..."). 

They are at least 5 different ways of using an API function: 

1. as a php function, to run your own code on the same server as CiviCRM 

2. via the AJAX interface, to be called from JavaScript code 

3. via the REST * interface, can be called from another server via http calls 

4. as a Smarty function to add data to templates 

5. from drush on the command line for Drupal installations. 
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Tip: When using the API, be sure to verify the proper name of each parameter, which 
parameters are mandatory, and the structure of the resulting array. The easiest way to test 
the API is to make AJAX calls from a test web page. See the AJAX section below for more 
information. 

*lt's not really REST, but it's not SOAP either. It doesn't work for many API functions because 
it assumes a certain level of standardisation that just isn't in place yet (as of version 3.2). 
Test, test, test if you use the REST (REST, REST) interface, and don't hesitate to file bugs 
when things don't work the way they should. 

CALLING THE API AS A PHP FUNCTION 

If you write custom code that is going to run within the same environment as CiviCRM, calling 
the API as a PHP function is the recommended way of modifying or fetching data. You will see 
examples of API calls throughout the developer documentation. 

For example, you could create several tags from a script rather than doing it manually from 
the CiviCRM admin page. The code below shows you how to do it using the API. 

Following the API convention described above, the function to call is civicrm_tag_create. The 
input parameters are: name, description, parentjd. 

<?php 

require_once ' civicrm . con fig .php ' ; 

require_once ' CRM/ Core/ Con f ig . php ' ; 

require_once ' api/v2/Tag.php ' ; 

Sparam = array ( "name"=>"Topic of interest"); 
Sresult = civicrm_tag_create ( Sparam ); 

if (civicrm_error ( Sresult ) ) 

die ("Topic of interest already exists"); 

$parentid = $result [ ■ tag_id' ] ; 

$tags = array { "Animal Protection", "...200 other tags", "Zen") ; 

foreach (Stags as Stag) { 

$params = array ( " name "=> Stag, " description "=> "Example of Topic of interest", 
$result = civicrm_tag_create (Sparam); 
if (civicrm_error ( Sresult )) { 

echo "\n ERROR creating Stag: ". Sresult [ ' error_message ' ] ; 
} else { 

echo "\n Tag Sname created with id: " . $result [ ' tag_id ■ ] ; 



Some explanations: 

• civicrm_error is a helper function to test if the api returned an error (or not) 

• all the functions are in api/v2; the name of the file is the name of the entity (in 
CamelCase). 

Tip: It is very easy to create a custom API class to add new methods to the API. Simply 
create a new file in api/v2/ with any name you want (and a .php extension) and put the 
functions in it. They should follow the naming convention explained above. Your new API 
functions will automatically be available. 

CALLING THE API AS AJAX BACK-END 

With Ajax, you can retrieve data from the CiviCRM server asynchronously in the background 
without interfering with the display and behavior of the existing page. 
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This section assumes you are familiar with over-riding templates and using jQuery. There is a 
chapter in this section on over-riding templates, and you can find more information on jQuery 
using any web search engine. 

All the API functions are directly usable from an Ajax call and available to all logged-in users 
with CiviCRM access privileges. This is very useful to update a value in the database without 
having to reload the whole page (which might contain a long list of records, for example). You 
could use it on the activities list page to set the status as "completed", on a list of 
participants to set the status as "attended", or to tag a contact in a search result, each time 
without having to reload the page. 

Using the jQuery plug-in 

The file js/rest.js contains a jQuery plug-in to make it simpler to call any CiviCRM API function. 

The general syntax is $().crmAPI (entity.action.params) 

For example, to dynamically create a tag, using JavaScript, in any page: 

$() .crmAPI ( "civicrm_tag" , "create", {"name": "Wonky", "description": "Wobbly c 

Upon completion of the Ajax call, the default behaviour is to display a "Saved" message in a 
div with id "restmsg" (you will need to be sure this div exists in your page if you want to see 
the message). However, you might want to alter this default behaviour, for instance to change 
the colour of a row, the name in a field or to hide a button the user has clicked. This is done 
via a special parameter, "success", that is a function called when the Ajax API has returned 
the result. The next example shows how this is used. 

Large organisations often have many contact records in CiviCRM and staff don't have time to 
update every detail of every record, even if they notice that the phone number doesn't work 
or the address isn't correct anymore. One solution is to allow them to flag the record for later 
follow-up if they suspect it may be inaccurate. 

To make this as simple as possible, create a button that tags the contact "To be checked". 
We can modify the contact summary screen (CRM/Contact/Page/View/Summary.tpl) and add a 
button "To be checked", that adds the tag via an Ajax call to the API. 



Here's what we added to the contact summary template to make this work (don't forget to 
create the "To be checked" tag): 

{literal} 

<script> 

jQuery (document) . ready {function ( $) { 

S ( "tactions" ). append {'' <lixa href="#" id="tobechecked" class="button" title= 
S(). crmAPI ( ' entity_tag' , 'add' , { 



tag_id 

, entity_table 
, entity_id 



6 

' civicrm_contact ' 

{/literal) {$ contact Id) {literal) 



success : function (){ 

$ ("ttobecheked") . f adeOut ( ' slow' ) , 



)) ; 
return false; 



)) ; 

</script> {/literal) 

A few points of explanation: 
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• The initial {literal} is to tell Smarty (CiviCRM's templating engine) that it should ignore 
everything that comes next until it sees {/literal}. This is needed because JavaScript uses 
the curly brace character and Smarty will become very confused if we don't tell it to 
relax beforehand. 

• In this specific example, the tag "to be checked" had 6 as its id, so adjust appropriately 
if you're following along at home. 

• entityjd: {/literal}{$contactld}{literal} means that {$contactld} is a smarty tag (and is 
replaced by a number, the id of the contact 

• When the contact has been tagged, the function success is called, and it removes the 
"To be checked" button from the toolbar. 

• It might be even better to have the button create a new activity "To be checked" that 
is assigned to the person responsible for checking contacts. The API to call would be 
civicrm_activity_create. The details of the parameters for the actual implementation is 
an exercise left to the reader. 

Ajax behind the scenes 

It is useful to know what happens when you use the Ajax interface to help you debug 
problems with it. 

The $().crmAPI call accesses a URL like this (for Drupal with clean URLs enabled): 

http : / /example . org/civicrm/a j ax/rest ?f nName-civicrm/<entity>/<action>& j son-l&pai 

To create a tag, for example, the following URL gets accessed: 

http : / /example . org/civicrm/a j ax/rest ?f nName-civicrm/ tag/create & j son=l&name-examf 

Tip: In order to test an API function that you want to use in your PHP code, a template, or via 
the REST interface, you can use the Ajax interface to figure out the right parameters. For 
instance, if you want to fetch all the tags of a contact (method civicrm_entity_tag_get), log in 
to CiviCRM and then paste this URL into your browser: 

http : / /example . org/civicrm/a j ax/rest? f nName=civicrm/entity_tag/get & j son=l 

It should return {"is_error":1,"error_message":"entity_id is a required field."} . So you add the 
entityjd (which should be the contact id in this case). Now try this one: 

http : / /example . org/civicrm/a j ax/rest ?f nName-civicrm/entity_tag/get & j son=l&entit^ 

... which returns: 

[ {"tag_id" : "4"} , { "tag_id" : "3" } , {"tag_id" : "1"} , { "tag_id" : "14" } ] 

You can also now see the format of the returned data. This should give you a good idea of 
how to use this API function in other contexts. 

Auto complete and search contacts 

If you create a profile for individual contacts that contains the current employer, you might 
want to add an autocomplete on that field, such as you have on the normal contact edit form. 
When a user starts to type the name of the current employer, the system will attempt to 
autocomplete the name from your database of organisation contacts. 

For security reasons, the Ajax interface is restricted to users who have access to CiviCRM - 
otherwise, it would be fairly easy for anyone to download all the contacts you have in your 
database. So that's the first thing we check for here: 

{if $session->get ( ' userlD ' ) > 0} 

<script type="text/j a va script" src="{$config->resourceBase}js/rest.js"></script- 

<script> 

j Query (document) . ready ( function ( S ) { 

$ ( ' #current_employer ' ) . crmAutocomplete ( {params : { contact_type : ' Organization ' } } ) 



234 



}) ; 
</script> 

{/literal} 

{/if} 

You might want to add additional filters. For instance in a profile "new volunteer from a 
member", you want to populate the list only with the organisations that belong to the group 
"members" (group id 42). 

S ( ' #current_employer ' ) . crmAutocomplete ( {params : { contact_type : 'Organization' , gi 

CALLING THE API FROM A TEMPLATE 

This section assumes you know how to find the template used to render a page and you know 
how to over-ride a template. Read the section on templating in the developer documentation 
if you're not sure. 

On some templates, you might want to display more information than what is available by 
default, for example, displaying the list of groups a contact belongs to next to his or her tags. 

You can use the API to fetch that information from within the template and assign it to a 
Smarty variable that you can then display just like any other variable. 

The general syntax is {crmAPI var="new variable name" entity="entity name" 
action="action name" param1="xxx" param2="yyy"} 

For example to fetch all groups the user id 42 belongs to and assign them to the variable 
groups: 

{crmAPI entity="group_contact" action="get" var="groups" contact_id=42 } 

The following code adds the list of groups below the list of tags on the contact summary page 
(CRM/Contact/Page/View/Summary.tpl) 

<tr> 

<td class="label">Groups</td> 

<td id="groups"> 
{crmAPI entity="group_contact" action="get" var="groups" contact_id=$contactId } 
{foreach from=$groups item=group} 
{ $group . title } , 
{ /foreach} 
</td> 
</tr> 

CALLING THE API FROM AN EXTERNAL SERVER VIA THE 
REST API 

The syntax and principle are identical to the other methods, but with one major difference: 
the external server needs to authenticate itself before being able to use any API functions. 

To call the API with a browser, use: 

http : / /www . example . org/path/ to/civi/codebase/civicrm/extern/rest . php?q=civicrm/< 

The first call is to authenticate the caller on the CiviCRM server: 

https : //www . example . org/path/ to /civi/codebase/civicrm/extern/rest . php?q=civicrm/ 

The key is in the CIVICRM_SITE_KEY variable defined in your civicrm. settings. php file. 

Note: On the first call, you might get an error message like "This user does not have a valid 
API key in the database, and therefore cannot authenticate through this interface". This 
means that you need to generate a key for the user, and add it to the api_key field in the 
civicrm contact table in the database. 
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{ "is_error" : , "api_key" : "as-in-your-setting. civic rm. php", "PHPSESSID" : " 4984783 cbH 

It returns a session id. You can then use any API adding the extra param PHPSESSID = the 
value returned by the log-in call. 

For example: 

http : / /www . example . org/civicrm/a j ax/rest ?f nName-civicrm/ contact/ search&json=l&ke 
yoursitekey&PHPSESSID=4 984783cb5ca0d51a622ff35fb32b5 90 

Note: An action that modifies the database (such as creating a contact or group) should have 
the parameters passed as POST, not GET. The REST interface accepts both a GET and a 
POST, but you should follow the web standard and use POST for things that alter the 
database. You'll win the respect of your peers and the admiration of your friends and family. 

Access the REST API from other languages 

The REST interface is language neutral (any language can use it as soon as it operates over 
HTTP requests), and 3 external libraries have been written by others in the CiviCRM 
community (and are in various states of completion): 

1. perl: http://search.cpan.org/~wmorgan/ 

2. ruby: http://github.com/cap10morgan/civicrm-client-rest-ruby 

3. python: http://dev.plone.org/collective/browser/collective.civicrm.pycivicrm/trunk 

Please refer to the documentation provided with each library to see how to use them (or 
complain to their authors if it is lacking). 
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55. 



HOOKS 



Hooks are a common way to extend systems. At key points in processing—such as saving a 
change or displaying a page--CiviCRM checks to see whether you've "hooked in" some custom 
code, and runs any valid code it finds. 

For example, let's say you want to send an e-mail to someone in your organization every time 
a contact in a particular group is edited. Hooks allow you to do this by defining a function with 
a specific name and adding it to your organization's CiviCRM installation. The name of the 
function indicates the point at which CiviCRM should call it. CiviCRM looks for these function 
names and calls them whenever it performs the indicated operations. 

Hooks are an incredibly useful way to extend CiviCRM's functionality, incorporate additional 
business logic, and even integrate CiviCRM with external systems. Many CiviCRM developers 
find themselves using them in nearly every customization project. 

USING A HOOK IS THE WRONG CHOICE WHEN ... 

If you just want to invoke an activity from CiviCRM in a program, it's more appropriate to use 
the API (covered in another chapter). For example, if you want CiviCRM to output everyone in 
a particular group so that you can feed them into an external database, you probably should 
use the API instead of a hook. 

A good test for whether or not to use a hook is to ask yourself whether what you're trying to 
do can be expressed with a sentence like this: "I want X to happen every time someone does 
Y." 

HOW TO USE HOOKS 

How you use hooks depends on whether you're using CiviCRM with Drupal or Joomla! 
Using hooks with Drupal 

Check the CiviCRM wiki page for the most up-to-date information on setting up hooks with 
Drupal: http://tiny.booki.cc/7hooks-in-drupal 

In order to start using hooks with a Drupal-based CiviCRM installation, you or your 
administrator needs to do the following: 

1. Create a file with the extension .info (for instance, myhooks.info) containing the following 
lines. Replace the example text in the first 2 lines with something appropriate for your 
organization: 

name = My Organization's Hooks 

description - Module containing the CiviCRM hooks for my organization 

dependencies [ ] - civicrm 

package = CiviCRM 

core = 6.x 

version - 1.0 

2. Create a new file with the extension .module (for instance, myhooks. module) to hold 
your PHP functions. 

3. Upload both the .info and .module files to the server running CiviCRM, creating a new 
directory for them under /sites/all/modules (for instance, /sites/all Vmodules/myhooks/) 
inside your Drupal installation. The directory name you create should be short and 
contain only lower case letters, digits, and underlines without space. 

4. Access the Drupal Administration page to enable your new hooks module. 
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Using hooks with Joomla! 

Check the CiviCRM wiki for the most up-to-date information on setting up hooks with Joomla!: 
http://tiny.booki.cc/7hooks-in-joomla 

In order to use hooks with Joomla!, you or your administrator needs to do the following: 

1. Create a file named civicrmHooks.php to contain your functions. 

2. Create a new directory anywhere on your server outside of your Joomla! / CiviCRM 
installation (so that upgrades will leave your hooks alone). /var/www/civicrm_hooks might 
be a good choice. 

3. Upload the civicrmHooks.php file to the directory you just created. 

4. Go to: CiviCRM Administer > Global Settings > Directories. Change the value of Custom 
PHP Path Directory to the absolute path to the new directory (e.g., 
"/var/www/civicrm_hooks" if you used that suggestion in the earlier step). 

Refine what you want to act upon 

When you create a hook, it will be called for all the types of entities. For instance, a 
civicrm_post is called after the creation or modification of any object of any type (contact, 
tag, group, activity...). But usually, you will want to make something happen only for a specific 
type of entity. 

So a hook generally starts with a test on the type of entity or type of action. For instance, if 
you want to act only when a new individual contact is created or modified, start your 
civicrm_post hook with: 

if ($objectName != "Individual" I I Sop != "edit") { 

return; 



On the other hand, if you want to run multiple hooks within the same function, you don't want 
to return from any single hook. Instead, you can nest the entire code for each hook within 
your test: 

if ($objectName == "Individual" && $op == "edit") { 
// Your hook 



Pitfalls of hooks 

Because you have little control over what CiviCRM passes to your hook function, it is very 
helpful to look inside those objects (especially $objectRef) to make sure you're getting what 
you expect. A good debugger is indispensable here. See the Developer Tips & Tricks chapter at 
the end of this section for more information on setting up a debugger for your development 
environment. 

EXAMPLES OF USING HOOKS 

Some example hooks follow. Consult the hooks reference documentation on the CiviCRM wiki 
to see the full extent of what you can do: 
http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+hook+specification 

In all of these examples, you'll put the code we provide into your myhooks. module file if using 
Drupal, or the civicrmHooks.php file if using Joomla!. Be sure to upload the file after each 
change to the appropriate location on your server to see the new code take effect. 

Additionally, if you are using Drupal and add a new hook to an existing module, you will need 
to clear the cache for the hook to start operating. One way of doing this is by visiting the 
page Admin > Build > Modules. 
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Sending an email message when a contact in a particular group is edited 

In order to have CiviCRM tell you when a contact is edited, define the civicrm_pre hook. This 
lets you see the incoming edits as well as the values of the existing record, because you may 
want to include that information in the email. 

If you are using Drupal, create a function named myhoo/cscivicrmpre. If using Joomla!, 
create a function named joomla_civicrm_pre. We'll assume you're using Drupal for the rest 
of the example, so please adjust the code accordingly if you're using Joomla! instead. 

<?php 

function myhooks_civicrm_pre ( $op, $ob j ectName , $objectId, &$objectRef ) { 

# configuration stuff 

$ the Group Id = 1 ; # group id we want the contacts to be in 
$emailRecipient - ' j ohndoe@ example .org 1 ; # person to e-mail 

# Make sure we just saved an Individual contact and that it was edited 
if ( $obj ectName —~ "Individual" && $op == "edit" ) { 

# Now see if it ' s in the particular group we ' re interested in 

require_once ' api/v2 /GroupContact . php ' ; 
$params = array (' contact_id' => $objectId); 
$groups = civicrm_group_contact_get ( $params ) ; 
$f ound = false ; 
foreach ($groups as $group) { 

if (Sgroup [ ' group_id' ] == StheGroupId) { 
$f ound = true; 



# Exit now if contact wasn ' t in the group we wanted 
if ( ! $found) { 
return; 



# We found the contact in the group we wanted, send the e-mail 
$emailSubj ect = "Contact was edited"; 

$emailBody = " Someone edited contactld $objectId\n"; 

# Here ' s where you may want to iterate over the fields 

# and compare them so you can report on what has changed. 
mail ( $emailRecipient , $emailSubject, $emailBody ) ; 



Validating a new contribution against custom business rules 

If you have experience with other hook-based systems, you might think that the civicrm_pre 
hook is the one to use for validations. But this is not the case in CiviCRM because, even 
though the civicrm_pre hook is called before the record is saved to the database, you cannot 
abort the action from this hook. 

This is where validation hooks come in. When you return true from a validation hook, CiviCRM 
saves the new or updated record. When you return an error object instead, CiviCRM aborts 
the operation and reports your error to the user. 

An example follows of using a validation hook to validate new contributions against a business 
rule that says campaign contributions must have a source associated with them. In this 
example, we'll assume you are using Joomla!, so if you are using Drupal instead, be sure to 
change the function name accordingly. 

<?php 

function j oomla_civicrm_validate ( $f ormName, &$fields, &$f iles , &$f orm ) { 

# configuration stuff 

$campaignContributionTypeId - 3; # adjust for your site if different 

$errors = arrayO; 

# $f ormName will be set to the class name of the form that was posted 
if ($formName == ' CRM_Contribute_Form_Contribution ' ) { 

require_once ' CRM/Utils /Array .php ' ; 
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$contributionTypeId - CRM_Utils_Array :: value ( ' contribution_type_id ' , 

$fields ) ; 
if ( ScontributionTypeld -- $campaignContributionTypeId) { 

# see if the source field is blank or not 

Ssource = CRM_Utils_Array: rvalue ( 'source', Sfields ); 
if (strlen( Ssource ) > 0) { 

# tell CiviCRM to proceed with saving the contribution 
return true; 

} else { 

# source is blank, bzzzzzzzzzzzt ! 

# assign the error to a key corresponding to the field name 
Serrors [' source ' ] = 

"Source must contain the campaign identifier for campaign contributions' 
return Serrors; 
} 
} else { 

# not a campaign contribution, let it through 
return true; 



Automatically filling custom field values based on custom business logic 

This example uses a hook to write some data back to CiviCRM. You can make a custom field 
read-only and then set its value from a hook. This is very handy for storing and displaying 
data that are derived from other attributes of a record based on custom business logic. 

For example, let's say you are storing employee records and you want to auto-generate their 
network login account when new employees are added. By doing it in your code, you can 
enforce a policy for login account names. For this example, let's say the policy is first initial + 
last name. So if your name is Jack Frost, your network login name would be jfrost. 

Add a new read-only custom field to CiviCRM called "Network Login" and then find its ID. You 
can find it either by: 

• Checking the civicrm_custom_field table in your CiviCRM database. 

• Editing a contact and check the name of the Network Login field. 

The code must refer to the ID as custom_/d. So if you find that the id of the new field is 74, 
refer to is as custom_74 in your code. 

Now that we have our Network Login field, let's see how to populate it automatically with a 
hook. We'll switch back to the Drupal naming convention for this example. 

Note that we use the civicrm_post hook here because we need the new contact record's ID in 
order to save a value to one of its custom fields. New records don't have an ID until they 
have been saved in the database, so if we ran this code in the civicrm_pre hook, it would fail. 

<?php 

function myhooks_civicrm_post ( $op, $objectName, $objectId, &$objectRef ) { 

# configuration stuff 
$customId = 74; 

if ($objectName == 'Individual' && $op == 'create') { 

# generate the login 

$firstName = $ob j ectRef ->f irst_name; 
$lastName = SobjectRef->last_name; 
$firstlnitial = substr ( $firstName, 0, 1 ); 
$networkLogin = strtolower ( $ f irstlnitial . $lastName ); 

# assign to the custom field 
$customParams = array ( "entitylD" => $objectId, 

"custom_$customId" => SnetworkLogin) ; 
require_once ' CRM/Core/BAO/CustomValueTable . php ' ; 
CRM Core BAO CustomValueTable : : setValues ( $customParams ); 
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The CiviMail component lets you customize a bulk email message using mail merge tokens. For 
instance, you can begin your message with, "Hi, {recipient. first_name}!" and when John Doe 
receives it, he'll see, "Hi, John!" and when Suzy Queue receives it, she'll see, "Hi, Suzy!" 

Besides the builtin tokens, you can use a hook to create new custom tokens. Let's make a 
new one that will show the largest contribution each recipient has given in the past. We'll use 
Drupal syntax again for this one. 

<?php 

# implement the tokens hook so we can add our new token to the list of tokens 

# displayed to CiviMail users 

function myhooks_civicrm_tokens ( sStokens ) { 

$tokens [ ' contribution ' ] = 

array ( ' contribution .largest' => 'Largest Contribution' ) ; 

/* just array (' contribution . largest ') ; in 3.1 or earlier */ 
} 

# now we ' 11 set the value of our custom token; 

# it's better in general to use the API rather than SQL queries to retrieve date 

# but in this case the MAX () function makes it very efficient to get the largest 

# contribution, so let's make an exception 

function myhooks_civicrm_tokenValues ( &$ details, &$contactIDs ) { 

# prepare the contact ID(s) for use in a database query 
if ( is_array ( ScontactlDs ) ) { 

$contactIDString - implode ( ' , ' , array_values ( $contactIDs ) ) ; 

$single = false; 
} else { 

$contactIDString = "( ScontactlDs )"; 

$single = true; 
} 

# build the database query 
$query = " 

SELECT contact_id, 

max ( total_amount ) as total_amount 
FROM civicrm_contribution 
WHERE contact_id IN ( ScontactlDString ) 
AND is_test - 
GROUP BY contact id 



# run the query 

$dao = CRM_Core_DAO: : executeQuery ( $query ); 
while ( Sdao->fetch( ) ) { 
if ( $single ) { 

S value =& $ de tails; 
} else { 

if ( ! array_key_exists ( $dao->contact_id, Sdetails 

Sdetails [ Sdao->contact_id] = array ( ); 
} 
Svalue =& $details [$dao->contact_id] ; 



# set the token's value 

$value [ ' contribution. largest ' ] = $dao->total_amount ; 
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56. 



IMPORTING DATA 



The CiviCRM import system can be used to import contacts, activities, contributions, event 
participants, and memberships. You can extend the import system to allow it to parse 
different data sources, such as XML, JSON, Excel, or OpenDocument. The import system is 
especially useful when you have legacy data in another system (such as a spreadsheet), or 
have data you need to migrate from one system to another. 

As of version 3.2, the import system has a few important limitations. It is currently not very 
good at importing: 

• Large data sets 

• Data sets which contain information for more than component (such as contact data 
that also contains contributions) 

• Data sets which should be imported into more than one group or tag (currently, you can 
choose only one group or tag for the entire import rather than specifying the value in a 
field of the imported data set). 

These limitation apply to any extensions you build on the import. To overcome these 
limitations, one strategy would be to write a custom script using the CiviCRM API that parses 
the incoming data and makes the appropriate API calls to import it. 

Note: If you're reading this in a printed copy, you may want to access the online version so 
you can copy and paste the code examples more easily. You can find the online version here: 
http://en.flossmanuals.net/civicrm 

DATA SOURCES 

The import system supports two data sources out of the box. CSV and SQL. CSV is exported 
by most spreadsheets, many web sites, and a lot of legacy systems. SQL is the language of 
relational databases. 

Here's your first insider tip on the import system: Every import is an SQL import. The CSV 
import data source, for example, starts out by dumping the CSV into a temporary database 
table and then running an SQL import on those data. If you write a custom data source, it's 
important to remember this because it will save you a lot of mental energy. You don't need to 
worry about formatting or validating the import data at all. Just get it into a database table 
and let CiviCRM take it from there. 

When would you want to write an import data source? It might be useful if, say, a client were 
migrating from another CRM to CiviCRM and wanted to import their data themselves. Another 
example would be to support a different import file format. 

To make things easy on yourself, check for an existing PHP library that can read the format of 
the data you want to import. If you fine one, use that library to read the data into a database 
table. 

DATA SOURCE API 

The data source API is essentially a set of functions you should implement in a new PHP class. 
Many software developers refer to this as an "interface" or "protocol." The abstract class that 
defines this interface is located in CRM/lmport/DataSource.php. You should also look at the 
CRM/lmport/DataSource/CSV.php file, because this implements the interface for the CSV import 
feature. 

Here are the functions you will implement and what they should do: 
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getlnf o ( ) ; # should return an array with the title of your data source plugin 
preProcess ( &$form ) ; # if you need to set anything up before the form is displc 
buildQuickForm ( &$f orm ) ; # here you should build a form snippet that asks the i 
postProcess ( &$params, &$db ) ; # this is where you dump the incoming data into t 

After defining your import data source, you need a new Smarty template to create your form 
snippet. This is pretty specific to the type of import data source you're defining. Let's look at 
an example of a real custom data source. 

EXAMPLE DATA SOURCE 

This example of a custom import data source reads a JSON file and imports its contents as 
new contacts. This file should be named JSON. php and be added to the 
CRM/lmport/DatoSource/ directory. 

<?php 

/ * My awesome JSON importer of dubious utility and efficiency (but still awesome 

* JSON should look like this: 

* { 

* "contacts" : [ 

{ 

* " f irst_name" : "Foo", 

* "last_name" : "Bar" , 

* "other field" : "baz" 



" f irst_name" : "Other" , 
"last_name" : "Contact", 
"something_else" : "yep" 



*/ 

require_once ' CRM/ Import /DataSource . php ' ; 

class CRM_Import_DataSource_JSON extends CRM_Import_DataSource 
{ 

function getlnf o ( ) 

return array (' title ' => ts (' JavaScript Object Notation ( JSON) ' ) ) ; 

function preProcess (&$form) 

# nothing to do here, but we still define the function 

function buildQuickForm f &$f orm) 

### In this function we' re calling a lot of QuickForm functions . 
### If you' re unfamiliar with that library, it might be good 
### to look up the documentation for it. 

# define a hidden field that tells the system which 

# data source class we're using 
$f orm->add ( 'hidden' , ' hidden_dataSource ' , ' CRM_Impor t_DataS our ce_ JSON' 

# grab the config object so we respect some system settings 
$config = CRM_Core_Conf ig : : singleton ( ) ; 

# get the max upload file size from the config 
$uploadFileSize = $conf ig->maxImportFileSize; 
$uploadSize = round ( ( $uploadFileSize / (1024*1024) ), 2 ) ; 

# assign the max upload file size to a template variable 

# see the template documentation for more info on this 
$f orm->assign ( ' uploads ize ', $uploadSize ); 

# add the file selection field to the form 
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$f orm->add ( ' file' , 'uploadFile ' , ts ( ' Import Data File' ) , 
1 size=30 maxlength=60 ' , true ) ; 

# now set the max file size so the form enforces it 
$f orm->setMaxFileSize ($uploadFileSize) ; 

$f orm->addRule { 'uploadFile' , 

ts ( ' File size should be less than %1 MBytes ( %2 bytes) ' , 
array (1 => SuploadSize, 2 => $uploadFileSize) ) , 
' maxf ilesize ' , $uploadFileSize ) ; 

# not a very smart rule, but it ' 11 do for now 

$f orm->addRule ( 'uploadFile', ts ( 'Input file must be in J SON format ' ) , 
'utf 8File' ) ; 

# make sure we end up with a file after the form posts 

$f orm->addRule ( ' uploadFile ' , ts ( ' A valid file must be uploaded . ' ) , 

' uploadedf ile ' ) ; 
} 

function postProcess (&$params, &$db) 
{ 

# grab the name of the file that was uploaded 
$f ile = Spa rams [ ' uploadFile ' ] [ ' name ' ] ; 

# call a helper function we'll define below to parse the JSON 
$result - self : :_JsonToTable ( $db, Sfile, 

CRM_Utils_Array :: value ( ' import_table_name ' , $ pa rams ) ) ; 

# grab the import table name (CiviCRM determines this for us) 
Stable = $result [ ' import_table_name ' ] ; 

# create a new ImportJob object for our table 
require_once ' CRM/ Import /ImportJob . php ' ; 
$importJob = new CRM_Import_Import Job ( Stable ) ; 

# the ImportJob modifies the table name a bit, so let's update it 
$this->set ( ' importTableName ' , $import Job->getTableName ( ) ) ; 



/** 

* We define this function just to keep things cleaner, the import data soui 

* interface doesn't look for it; it's a private function. We use an 

* underscore at the beginning of the name to indicate this. 
*/ 

private static function _JsonToTable ( &$db, Sfile, Stable ) 
{ 

# read the JSON into a string variable 
SjsonString - f ile_get_contents ($file) ; 
if ( ! SjsonString) { 

# oops, reading the file didn't work, generate an error 
CRM Core Error :: fatal ( "Could not read Sfile"); 



# grab the config object again 
Sconfig - CRM_Core_Conf ig : :singleton() ; 

# this is a bit presumptuous of us, but oh well 
Sdb->query ("DROP TABLE IF EXISTS Stable"); 

# create the table where we'll store the incoming data 
S create = "CREATE TABLE Stable LIKE civicrm_contact" ; 
Sdb->query ( Screate) ; 

# drop the id column because the import system will add one 
Sdropld ~ "ALTER TABLE Stable DROP COLUMN id"; 
Sdb->query ( Sdropld) ; 

# decode the JSON and INSERT the records one by one; 

# it might be more efficient to build one big multi-insert, 

# but we ' 11 leave that as an exercise for the reader 

### BE CAREFUL THAT YOU DON'T RUN THIS ON A MASSIVE JSON FILE!! 

### It creates one big object from the entire JSON file, so you'll quic> 

### eat up every bit of memory PHP can use if you try to import a large 

### file. 

# this requires that the JSON PECL extension is installed and 

# enabled in PHP 

SimportObj = json_decode( SjsonString, true ); 
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# loop through each record in the JSON object, put it into an SQL query, 

# and insert it into the database 

foreach ($importObj [' contacts ' ] as $newContact) { 

Sfields = array_map ( ' _civicrm_mysql_real_escape_string ' , 

array_keys ( SnewContact ) ) ; 
SsqlFields = "(" . implode ( ',', $fields ) . ")"; 
Svalues = array_map ( '_civicrm_mysql_real_escape_and_quote_string' , 

SnewContact ) ; 
SsqlValues - "VALUES (" . implode) ',', $values ) . ")"; 

# construct the query and run it 

Ssql - "INSERT IGNORE INTO $table $sqlFields SsqlValues"; 

Sdb->query ($sql) ; 



# get the import tmp table name and return it 
$result = array ( ); 

$ result [ ' import_table_name ' ] = Stable; 
return Sresult; 



# Another couple private helper functions we define 

function _civicrm_mysql_real_escape_and_quote_string ( Sstring ) { 

return _civicrm_mysql_real_escape_string ( Sstring, true ) ; 
} 

function _civicrm_mysql_real_escape_string ( Sstring, $ quote = false ) { 
static Sdao = null; 
if ( ! Sdao ) { 

Sdao = new CRM_Core_DAO ( ); 
} 
SreturnString = Squote ? " \ " { Sdao->escape ( Sstring )}\"" : 

Sdao->escape ( Sstring ); 
return SreturnString; 
} 

And here's the Smarty template. It should be saved in templates/CRM/lmport/Form/JSON.tpl. 

<fieldsetxlegend>{ts}Upload JSON File { /ts } </legend> 
<table class=" f orm- layout " > 
<tr> 

<td class="label">{$form.uploadFile . label }</td> 
<td>{ Sform.uploadFile.html }<br /> 

<div class = "description">{ts }File format must be JavaScript Obj ect 1? 
{ts l=$uploadSize}Maximum Upload File Size: %1 MB{/ts} 
</td> 
</tr> 
</table> 
</fieldset> 

SUMMARY 

The CiviCRM Import system has a few limitations, but it is by far the easiest way for end 
users to get data from other systems into CiviCRM. When a client has ongoing data import 
needs and wants non-technical users to initiate and manage the imports, writing a custom 
data source may be a good solution. 

If the import system cannot handle the type or amount of data you need to import, your 
options are to write a separate import program that calls the CiviCRM API, write your own 
improvements to the import system, or sponsor other developers to write improvements. If 
you write or sponsor improvements to the import system, make sure you contribute them 
back to the core system! The CiviCRM development team would be happy to discuss potential 
improvements with you. You can find them in the #civicrm IRC channel on irc.freenode.net. 
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57. 



TIPS & TRICKS 



There are a few practices that seasoned CiviCRM developers have found very helpful when 
working on CiviCRM projects. This chapter contains a few of them, as well as some guidance 
on how to make use of them yourself. You don't have to use any of these tips, but they have 
made many other developers' lives easier, so give them a try and see if you agree. 

RUN A LOCAL DEVELOPMENT INSTANCE OF CIVICRM 

When hacking on CiviCRM customizations and extensions, you don't want to interrupt your 
users' work or corrupt the data in the CiviCRM database. That's why you should never, ever 
hack on the same instance of CiviCRM that other people are using to store and work with live 
data. That's a recipe for disaster. Instead, load CiviCRM and its associated programs onto your 
own development "sandbox," where you can do whatever you want to CiviCRM without 
disturbing anyone else. 

If your computer runs Linux or Mac OS X, running CiviCRM on your local machine is pretty 
easy. If your computer runs Windows, you have a little more work to do, but it's not 
impossible. You should seriously consider running Linux inside a virtual machine (there's a free 
program called VirtualBox that makes this pretty easy). We recommend running the latest 
version of Ubuntu Linux inside the virtual machine. You can download that here: 
http://www.ubuntu.com/ 

Preparing your machine to run CiviCRM 

These instructions will tell you how to prepare your system to run CiviCRM. Jump to the 
section that matches your operating system. 

Debian / Ubuntu Linux 

sudo apt-get install apache2 php5 libapache2-mod-php5 mysql-server \ 
libmysqlclientl5-dev php5-mysql php-db 

Red Hat / CentOS Linux 

sudo yum install php-xml 

Mac OS X 

Mac OS X does not have a built-in package manager like most Linux distributions do, but there 
are some third-party ones you can install. MacPorts is a good choice. The installation 
instructions can be found here: http://www.macports.org/install.php 

Once MacPorts is installed, open up Terminal (in Applications -> Utilities) and run this command 
(quit Terminal first and re-launch it if you already had it running): 

sudo port install apache2 mysql5-server php52 tpear +mysql5 

Be sure to read the output of that command carefully, because there are often further tasks 
you need to perform to enable some of the packages (especially PHP and MySQL). 

Next Step for All Operating Systems 

Follow the CiviCRM installation instructions already provided in the documentation. You can find 
these instructions here: 
http://wiki.civicrm.org/confluence/display/CRMDOC/lnstallation+and+Upgrades 
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USE XDEBUG 

This is our main recommendation for developers. Readers familiar with what a debugger is and 
how it works should feel free to skip ahead to the "Setting Up XDebug" section. 

What is a debugger? 

A debugger is a software program that watches your code while it executes and allows you to 
inspect, interrupt, and step through the code. That means you can stop the execution right 
before a critical juncture (for example, where something is crashing or producing bad data) and 
look at the values of all the variables and objects to make sure they are what you expect 
them to be. You can then step through the execution one line at a time and see exactly 
where and why things break down. It's no exaggeration to say that a debugger is a developer's 
best friend. It will save you countless hours of beating your head against your desk while you 
insert print statements everywhere to track down an elusive bug. 

Debugging in PHP is a bit tricky because your code is actually running inside the PHP 
interpreter, which is itself (usually) running inside a web server. This web server may or may 
not be on the same machine where you're writing your code. If you're running your CiviCRM 
development instance on a separate server, you need a debugger that can communicate with 
you over the network. Luckily such a clever creature already exists: XDebug. 

Setting Up XDebug 

XDebug isn't the only PHP debugger, but it's the one we recommend for CiviCRM debugging. 

The instructions for downloading and installing XDebug are here: http://xdebug.org/docs/install 

Those instructions are a bit complex, however. There is a far simpler way to install it if you 
happen to be running one of the operating systems listed here. 

Debian / Ubuntu Linux 

sudo apt-get install php5-xdebug 
Red Hat / CentOS Linux 

sudo yum install php-pecl* php-devel php-pear 
sudo peel install Xdebug 

Mac OS X 

sudo port install php5-xdebug 

Next Step for All Operating Systems 

Tell XDebug to start automatically (don't do this on a production server!) by adding the 
following two lines to your php.ini file: 

xdebug. remote_enable = On 
xdebug. remote_autostart = 1 

Once XDebug is installed and enabled in your PHP configuration, you'll need to restart your 
web server. 



Installing an XDebug Front-End 
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After you have XDebug running on your PHP web server, you need to install a front-end to 
actually see what it is telling you about your code. There are a few different options available 
depending on what operating system you use: 

All Operating Systems 

NetBeans is a heavyweight Java IDE (Integrated Development Environment). It offers lots of 
features, but isn't exactly small or fast. However, it is very good at interactive debugging with 
XDebug. And since it's written in Java, it should run on any operating system you want to run 
it on. You can find it at http://www.netbeans.org / 

After installing NetBeans, open your local CiviCRM installation in NetBeans and click the Debug 
button on the toolbar. It will fire up your web browser and start the debugger on CiviCRM. You 
may went to set a breakpoint in CRM/Core/lnvoke.php to make the debugger pause there. For 
more information, see the NetBeans debugging documentation. 

Mac OS X 

A much lighter-weight option for Mac users is a program called MacGDBp. You can download it 
here: http://www.bluestatic.org/software/macgdbp/ 

After installing MacGDBp, launch it and make sure it says "Connecting" at the bottom in the 
status bar. If it doesn't, click the green "On" button in the upper-right corner to enable it. The 
next time you access CiviCRM, the web browser will appear to hang. If you click on MacGDBp, 
you'll see that it has stopped on the first line of code in CiviCRM. From there you can step 
through the code to the part you're interested in. But it's probably a better idea to set a 
breakpoint in the part of the code you're interested in stopping at. See the MacGDBp 
documentation for more information. 

DEBUGGING TIPS 

Note that to use these tips this you need to enable your Debugging in CiviCRM. 

• Smarty Debug Window 

Loads all variables available to the current page template into a pop-up window. To 
create this window, add &smartyDebug=1 to any CiviCRM URL query string. Make sure 
you disable pop-up blocking in your browser for the CiviCRM site URL. 

• Session Reset 

Resets all values in your client session. To trigger this, add &sessionReset=2 

• Directory Cleanup 

Empties the template cache and/or the temporary upload file folders, 
o To empty template cache (the civicrm/templates_c folder), add 

&directoryCleanup=1 
o To remove temporary upload files (the civicrm/upload folder), add 

&directoryCleanup=2 
o To clean up both, add &directoryCleanup=3 

• Stack Trace 

To display a stack trace listing at the top of a page, add &backtrace=1 

LOG EMAILS TO A FILE 

For this you need to modify your CiviCRM settings (http://civicrm.settings.php) and add 
following line: 

define ( ' CIVICRM_MAIL_LOG' , ' <path to of the file >/mail . log ' ) ; 

CHECK THE QUERIES FIRED BY DATAOBJECT 

define ( ' CIVICRM_DAO_DEBUG ' , 1 ) ; 
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FOREIGN CONSTRAINT ERRORS 

If you are getting foreign key constraint errors, try logging out from CiviCRM and logging in 
again. 

HOW TO FIND THE TEMPLATE FILE 

Finding which template is used on a given page can be difficult. The easiest way is to view the 
source of the page from a web browser and search for ".tpl". For instance, for the contact 
summary page, use the web browser to access the contact summary page, then click "View 
Source" in the browser. You should find an HTML comment such as: 

<!-- .tpl file invoked: CRM/Contact/Page/View/Summary . tpl . Call via form. tpl if 

USE A SOURCE CODE MANAGEMENT SYSTEM 

The source code of CiviCRM is accessible via Subversion. Although installing Subversion on your 
own computer is a bit complex, it is worthwhile using source control for your development 
website. 

You should also use a local source code manager (git or mercurial are good solutions) to keep 
track of your modified files. The workflow that has been proven most efficient is to copy the 
original file, add it to your repository and then modify it. 
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58. 



INTERNATIONALISATION 



CiviCRM is written in English. It has however also been built for organisations worldwide. They 
need to be able to adapt the tool to local circumstances and demands without modifying the 
tool technically. 

Localising CiviCRM (or any software) affects much more than you might initially think. To adapt 
CiviCRM to a local language is not just a matter of translating the text displayed on the 
screen, there are many other issues to consider. Consider for example specific settings for 
different regions, such as the currency used in a given country (USD or $ in United States, GBP 
or £ in Great Britain), date and time formats (for example: November 16th, 2009 will be 
commonly written as 11/16/2009 in United States, but in Russia the format will be 16.11.2009) 
or the formatting of numbers (the same number will be written slightly differently in different 
countries: 1 234 567,89 in Slovakia or Hungary, but 1,234,567.89 in Japan or the United States). 

Settings - Localization 



Language and Currency 



DQfault Language English (USA) 



Default language used for this Installation. 

Inherit CMS Language Q 

If checked. CiviCRM will follow CMS language chang.es. 

>($) 'I 



Qefault Currency 



Default ciirrerK^ assigned to eantrftuaoni and other rrn&neteiY transactions. 



Available currencies 







FJD (s) 

FKP [£) n 

GEL 

GUCft) 


| Add > > < < Remove | 
I 


USD [$) 
EUR[C) 







Monetary Locale 



English (USA) 



' 



. POFTOBtDFlfl ^|Jrt'iriefS pelow]. 



CiviCRM provides plenty of functionality to support these language and region specific needs. 
The development team is constantly developing new tools in this area too. 

TRANSLATIONS 

CiviCRM provides the ability for different languages to be used, however we rely on the 
community to translate parts or all of the text a user sees in CiviCRM. 

A number of languages have already been translated to a level. Some have more than 90% of 
the text translated, others only 5%, and a number of languages have not been translated at 
all. Please check the online translation tool Transifex 

(http://www.transifex.net/projects/p/civicrm/) to find out about your language of interest, 
download and install it on your CiviCRM install to find out how well it will suit your needs. 

You may find that although the translation is correct, you would want to use different terms 
in your situation. You are very much encouraged to take part in the translation of your 
language. 

FACILITIES 



A number of facilities are provided to support the community in its translation efforts, though 
some are still under development. 
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1. Transifex is an online tool that enables (groups of) translators to translate strings of 
text and keep an overview on its progress. Register there, look for your language, join 
the team or, if not available, start translating. 

2. There is a glossary 
(http://wiki.civicrm.org/confluence/display/CRM/Glossary+for+translations) on CiviCRM's 
wiki that will help you maintain consistency in your translations, but will also help you get 
some insight on how much work it will be to translate those strings of text that your 
users will most often get to see and would therefore be the first to translate. 

3. There is a tips and tricks wiki page 
(http://wiki.civicrm.org/confluence/display/CRM/Loca lisation+community+building+howto) 
with information on how to set up your localization community. 

4. There is also a FAQ 

(http://wiki.civicrm.org/conf luence/display/CRM/Getting+started+with+CiviCRM+Localisation+FAQ 
) on the CiviCRM wiki to help you. 

GETTING STARTED 

Feel like helping translating CiviCRM to a new language or improving the current translation? 
Here's how to do it in three easy steps (provided you have a bit of a technical background): 

1. Go to transifex.net and create an account 

2. Then look for your language on http://www,transifex.net/pro)ects/p/civicrm/teams/ and 
either join a team, or request the creation of a new one if needed. 

3. Start translating! 

Team work 

The CiviCRM translation work flow is still a work-in-progress and until the process becomes 
more mature, you should probably refer to 

http://wiki.civicrm.org/confluence/display/CRM/Localisation+community+building+howto for the 
most current instructions. 

The work flow is heavily based on teamwork. Hopefully, there is already a team of translators 
for your language that you can join. This team will have built a glossary, will have started a 
translation set and will be able to review your translations and give constructive criticism. If 
such a team does not yet exists, the opportunity is all yours to create one! 

Becoming a translator and joining a team 

Whether there is a already a team for your language or not, the first step in becoming a 
translator for CiviCRM is to create an account on transifex.net. Once your have done this, you 
should look for a language team on http://www.transifex,net/projects/p/civicrm/teams/ . If no 
team exists for you language and locale, you can offer to become the coordinator of a new 
team and help create it. 

COMPONENTS AND FILES 

There are quite a big number of strings (phrases) to translate in CiviCRM. To make it more 
easy to translate the part that you are interested in (hopefully the one you know best), the 
strings that need translation have been divided into components, which are CiviCRM plugins 
(CiviCRM core, CiviMail, CiviContribute, etc.). A separate component should be available for 
each version of CiviCRM, starting with version 3.2 (or 3.1, for language teams that have chosen 
to do so). 
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Each component itself contains a number of files, which themselves contain the strings to 
translate: the main component "CiviCRM" (the core) has close to 20 files (for countries, 
provinces, menu, etc.). 

TOOLS AND TECHNICAL DETAILS 

Depending if you do translation online or offline, the process will be different. Online translation 
does not require installation of any software. Offline translation is done on files downloaded 
from the translation website, using software that offers more features than the online 
system. 

For more details on this, please refer to the paragraph below, called Offline translation. 

Online translation 

Transifex is the tool to use for online translation. It does not have as many features as an 
offline tool such as PoEdit, but it's the easiest way to contribute translations, and do the 
occasional quick correction. Every translator should have an account on the transifex site, 
since translation teams can use the forums and messaging system to coordinate. 

Here are the basic steps to do translation: 

• first select a component on http://www.transifex,net/projects/p/civicrm/ : this will display 
the list of language teams for this component; 

• then click on the icon in the "Options" column next to the language you are interested 
in: this brings you to the list of files for this component; 

• then click on the "pencil and paper" icon: this brings you to the online translation screen, 
which lists all the translatable strings in this file; 

• for each string, you can then enter a translation 

• when you are done, you can click on the "Send for review" button at the end of the 
page- 
Offline translation 

Most translation is usually done with an offline translation tool. One of the most common is 
PoEdit (see http://www.poedit.net) , which is free software and has a big community of users. 
The exact steps to take to translate using an offline tool will depend on your tool of choice, 
but should follow the following steps: go on transifex.net and download the files you want to 
translate, load them up in your translation tool and send them back on the site when you are 
done. 

Building a translation memory 

PoEdit and other translation software will help you build a translation memory for your 
language. This translation memory can be built either only from the translations done in 
CiviCRM, or can include translations from other projects. Be aware that if you include other 
projects, automatic translation might be able to translate more strings, but you will lose 
consistency and that most strings will be marked fuzzy. This could be a way to bootstrap a 
new translation though. 

Building a translation memory based on words from the glossary could go a long way in 
insuring the consistency of your team's work. 

Using version control (mostly for programmers) 

Transifex keeps files in a version control system. These files are available on 
http://github.com/civicrm/HOn . This is useful to some users who find this easier than 
downloading each file separately from transifex. 
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Consistency & consensus 

To insure a good consistency in the translation, every team is encouraged to build and use a 
glossary, while also enforcing a peer review process. You can find a glossary of common terms 
on http://wiki,civicrm.org/confluence/display/CRM/Glossary+for+translations , You definitely 
should translate these terms to your language, and make sure you teams reaches a 
consensus on all terms. 

Eventually, building and sharing a common translation memory, which is like a specialized 
glossary that can be used automatically by translation tools, also helps insuring consistency. 
PoEdit help system will explain how to build this database (and most other translation 
software should do the same). 

TEAM BUILDING AND SPRINTS 

A good way to make good progress in translation is to organize translation sprints. This means 
getting as many people as possible together in the same room(s) to translate as many 
documents as they can. Here's a few things you should keep in mind when organizing a 
translation sprint: 

• choose a good location, where people will be able to get online (enough computers for 
everybody, or desks to setup laptops and with a decent internet connection); 

• provide instructions in advance on how to install an offline translation tool like poedit and 
have people ready to help others installing and using it; 

• present the glossary, discuss terms which do not have consensus and make sure 
everybody has access to a copy of it, print a sufficient amount of copies beforehand; 

• determine goals for the sprint: which component will be translated, what percentage 
your team is trying to achieve; 

• make sub-teams with clear objectives: per component or file or part of it; 

• if necessary, do a demo of the CiviCRM features your team is about to translate; 

• clearly designate someone who can be interrupted in order to answer questions; 

• at the end of the sprint, present the result of the translation in a demo CiviCRM 
installation; 

• discuss whether the team has reached its goal and how to improve further; 

• ...make sure you've got enough coffee, tea, chocolate in reserve to keep everybody 
going through the night. 
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59. 



BUG REPORTING 



There will be times when you use CiviCRM - as there are when you use any software - when 
things don't work the way you expect them to. 

When this happens, a good first step is to search the forums for similar problems and follow 
advice given there. If your problem hasn't been addressed, posting to the forum is probably 
the right thing to do. 

Have a look on the forum for good posting guidelines and spend a bit of time writing your post. 
Make sure you are detailed and specific about what software you are using, what you are 
trying to do and how you are trying to do it. For example letting people know the url you are 
using (with any confidential details removed) may cause them to realise that you are 
configuring the wrong page. Unclear posts are less likely to get good replies. 

WHAT CAUSES PROBLEMS WITH CIVICRM? 

Check the following possible sources of problems before you report something on a forum. You 
can save yourself and a lot of people trouble by isolating the problem. CiviCRM forums try to 
be friendly and don't criticise you for misjudging a problem, but you'll certainly get more help 
and resolve problems faster by doing some checking of your own first. 

• Misunderstanding the software. We don't claim our documentation is perfect. But 
please go back and check it very carefully when you hit a barrier. Frustration makes it 
hard to concentrate, so be sure to read slowly and thoroughly. Also remember that 
different parts of CiviCRM depend on each other, so check for problems in related 
modules, besides the one you think the problem is in. 

• Your server set up. Servers can be configured in many different ways, and these 
settings can change the way CiviCRM operates. Depending on your issue your server 
configuration may be causing you issues. 

• Customisations made to the source code of your installation of CiviCRM. Any changes 
made to the source code of CiviCRM may have unintended consequences. The 
community forums may be able to help you, but you will have to be patient, share 
source code, and try out suggestions. 

• Bugs in the version of CiviCRM you are using. After you have eliminated all the previous 
options, you can report your problem as a bug. In fact, we appreciate you doing this, 
because you are making CiviCRM better for everyone. 

RECREATING YOUR PROBLEM ON THE DEMO SITE 

Recreating your bug on one of the demo sites helps determine whether your problem is a 
result of a bug in the source code, or as a result of changes on your site, such as your server 
setup or any customisations you've made to the code. If you can show us that the code on 
the demo site turns up your bug, it's very likely that the CiviCRM source code is the problem, 
and your demonstration will help us find and fix it. 

Still, no demo site can cover all possibilities. So even if you can't reproduce your bug there, it 
might still be a bug in CiviCRM. It is, however, probably triggered by your server setup or other 
customisations. 

Write to the forum and explain the problem you are experiencing. If the bug was reproduced 
on the demo site, describe exactly what you did there. If not, include as much information 
about your server setup as you feasibly can. Configuration files from the web server, CMS, 
and CiviCRM will be valuable. 
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If the forum suggests you discovered a bug in CiviCRM, you can report it to the CiviCRM bug 
tracker (http://issues,civicrm,org/jira/browse/CRM) . 

USING OLDER VERSIONS OF CIVICRM 

If you are using an older version and the problem you are experiencing is a bug that has been 
fixed in the lastest release, be prepared for the answer that it is time to upgrade to the latest 
version. Although the CiviCRM community tries to be as helpful as possible, and we recognize 
that upgrading puts a burden on your organisation, it is difficult to support multiple versions 
simultaneously. 

FIXING BUGS 

The amount of time taken for the bug to be fixed depends on the severity and complexity of 
the bug. It could be as quick as the same day, but it could take much longer. 

To get bug fixes, the easiest way is just to download and install the latest revision of CiviCRM. 
Downloading bug fixes between releases and fixing ('patching') your existing software is 
possible, but it's a more involved process and depends on your technical ability and server 
setup. 
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60. 



FREE SOFTWARE? 



CiviCRM is Free Software - this means it is developed by a community and licensed in a 
generous way so you can use it for free for whatever you want. 

Free Software (sometimes also referred to as Free and Open Source Software, FLOSS, 
FOSS, Software Libre, or Open Source) is software that anyone can download, share, and - 
- significantly -- change in any way they want. Practically speaking, you might never want to 
change the software, or even have a staff person who can read the source code (the 
instructions written by programmers). But the ability to change the software protects you in 
many ways: 

• CiviCRM will not go away, unlike non-free software from some companies that gets 
abandoned if the company goes bankrupt or decides to discontinue specific product. 

• The software can be used and customised free of charge. 

• Nobody can suddenly take away features or change the terms under which you're 
allowed to use features. 

• If an organisation wants a feature that CiviCRM doesn't provide, the organisation can 
just hire someone to create it. Of course, the organisation can also submit a feature 
request to the CiviCRM team as with any software product. 

• Similarly, anyone can fix a bug (error in the software) if he or she has the skills to do so. 
Because the source code is available, clients can also find bugs more easily. 

• Members of the community have much more input into how CiviCRM develops, because 
they can understand the product by reading the code and can make changes. 
Furthermore, many people can try different implementations of features and the 
community can decide by vote or consensus which one to make official. 

That may be enough for you, but for the sake of completeness we'll offer some widely used 
definitions: 

"Free software or software libre is software that can be used, studied, and modified without 
restriction, and which can be copied and redistributed in modified or unmodified form either 
without restriction, or with minimal restrictions only to ensure that further recipients can also 
do these things and that manufacturers of consumer-facing hardware allow user modifications 
to their hardware. Free software is available gratis (free of charge) in most cases." 
(from: http://en.wikipedia.org/wiki/Free_software) 

"Open source software (OSS) is defined as computer software for which the source code 
and certain other rights normally reserved for copyright holders are provided under a software 
license that meets the Open Source Definition or that is in the public domain. This permits 
users to use, change, and improve the software, and to redistribute it in modified or 
unmodified forms. It is very often developed in a public, collaborative manner." 
(from: http://en. wikipedia.org/wiki/Open_source_software ) 

Nearly any software that qualifies as free also qualifies as Open Source, and vice versa. The 
main reason that two different terms exist is that "free software" emphasizes the freedom 
aspect (that you aren't under the control of the original programmers) whereas "open source 
software" emphasizes the convenience and potential for innovation provided by having the 
source code available. 

When you install and use CiviCRM, you'll notice there's no annoying click-through software 
license imposing a thousand things that you can or cannot do with it. That's because free 
software doesn't limit your right to do with the software whatever you want. Free and open 
source software have licenses, but they're simpler than and quite different from proprietary 
software ('closed software') licenses. CiviCRM itself is available under Affero General Public 
License version 3.0, one of the popular free software licenses used by many other projects. 
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FREE SOFTWARE AND NON-PROFITS 

Explaining all of the possible considerations on using FOSS in non-profit and advocacy work 
might take a really long time, so let's focus on the most important highlights: 

• One of the priorities of FOSS projects, including CiviCRM, is to involve the community of 
users in the process of designing and building the software. In the long run, this not only 
assures that the software is doing exactly what it should do to sustain the needs of its 
users, but it also allows indirect exchange of knowledge and experience between 
organisations. By using CiviCRM, you're basically taking advantage of other non-profit 
and advocacy practitioners' experience. 

• Having access to the source code gives you and your organisation certain independence. 
With proprietary software it's usually impossible to customise the tools to meet your 
specific needs. With FOSS, you can hire a developer or consultant and work with them 
on providing specific functionality needed in your work. Additionally, if you contribute 
your improvements to the project community other organisations will most probably 
start using them. It means you can receive testing and further improvements of your 
functionality. 

• When a company which provided you with a closed software goes out of business, the 
usual procedure for an organisation reliant on that software is to abandon the software 
and start investing in a new one (which is resource intensive and costly). It's less likely to 
happen with Free and Open Source Software - there is always a community of users 
and developers around it and there is no single "point of failure". With FOSS projects, if 
the main organisation behind a specific piece of software shuts down or changes their 
focus, the community takes over, a new organisation is formed and the software 
development and support continues. 

Apart from the quite practical advantages listed above, there is also a more philosophical 
approach to answering the question of importance of FOSS for non-profits and advocacy 
organisations. Without getting too deep into philosophical discussions, there is a great overlap 
between values shared by non-profit organisations and these shared by Free and Open Source 
Software communities. By working with the community of users, providing your feedback, 
contributing your changes back into the project, you're actually strengthening the non-profit 
sector. 

FURTHER READING 

Free Software Foundation 

http://www.fsf.org/ 

The Free Software Definition 

http://www.gnu.org/philosophy/free-sw.html 

Open Source Initiative 

http://www.opensource.org/ 

The Open Source Definition 

http://www.opensource.org/docs/osd 

GNU Affero General Public License v3 

http://www.opensource.org/licenses/agpl-v3.html 

Choosing and Using Free and Open Source Software: A primer for nonprofits 

http://www.nosi.net/projects/primer 
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61. 



ABOUT THIS MANUAL 



This second edition of the CiviCRM manual was written during a 4 day Book Sprint organized 
by CiviCRM and led by FLOSS Manuals. The sprint was sponsored by the Information Program 
initiative of the Open Society Institute http://www,soros,org/initiatives/information) . We are 
especially grateful to Janet Haven for pushing this forward. 

The Second edition includes new sections on CiviReports, CiviCase, CiviEngage and Extending 
CiviCRM. This edition also included an extensive re-write of nearly every section of the text, 
including a re-organization of all sections to break up information into Introduction, Planning, 
Configuration and Everday Tasks sections, the latter to serve as an easily consumed user 
manual for individuals working with CiviCRM on a daily basis. We also simplified and clarified the 
information Project Managers need, and we added an entire new section to assist developers 
get into the code. Finally, we updated the book to match CiviCRM 3.2 (which is a few weeks 
away from release at the time of writing). 

Here are the people that worked on this second edition of the text: 




The original manual was written during a 5 day Book Sprint organised by CiviCRM and led by 
FLOSS Manuals. The sprint was sponsored by the Information Program initiative of the Open 
Society Institute http://www.soros.org/initiatives/information) . We are especially grateful to 
Janet Haven for pushing this forward. 

Having secured sponsorship, the CiviCRM Core team invited a group of people from around the 
globe to gather for a week at Lake Tahoe in California. The modest goal was to transform our 
diverse experience of CiviCRM into a manual that we hope will help people to use this great 
piece of software. This turned out to be an interesting, and at times difficult, challenge. 

Here are the people that wrote this book. 
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In the back row you are looking at Michael McAndrew (London, UK), Tony Guzman (Salt Lake 
City, USA), Brian Shaughnessy (Albany, NY, USA), Dave Greenberg (San Francisco, USA), 
Yashodha Chaku (Mumbai, India) and Adam Hyde (Berlin, Germany). In the front row Mari Tilos 
(San Francisco, USA), Cynthia Tarascio (Philadelphia, USA), Michal Mach (Warsaw, Poland) and 
Peter Davis (Wellington, New Zealand). In the very front is Eileen McNaughton (Wellington, New 
Zealand). 

We came from different backgrounds, had used CiviCRM in different ways, and had worked 
with very different organisations. It was often a challenge to meld these perspectives into a 
cohesive whole but we hammered away at it and we think this made for a better book. We 
had some lively discussions about important issues, such as whether there is a 'z' or an 's' in 
organis/zation or a 'q' in check/que, and finally agreed to use both spellings in the spirit of 
internationalism. We also struggled with the word 'constituent' which is core to the non-profit 
sector in America but was unfamiliar to those of us from outside America. 

It has been a pretty intense five days. Adam (our friendly Floss manuals taskmaster) has kept 
us realistic, on track, and hard at work - even hauling us back to work after dinner each 
evening. Overall it has been both fun and productive and we really appreciate the way Adam 
has helped us to actually produce a book within a week. Thank you. 

For most of us, however, the highlight of the week has been the breathtaking cuisine cooked 
by Jill Klein (http://www.partiesthatcook.com/about-us/) . We love you Jill and wish we could take 
you home with us. We are also grateful to Dave Greenberg, Bob Concannon and Mari Tilos for 
their hospitality, and to Scout the dog just for being there. 
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We have had help from around the world during the preparation process, and over the course 
of the Sprint. Andy Oram has helped us both in the planning process and then with editing and 
feedback during the Sprint. We also had a number of people log in to write and edit the 
manual during the Sprint. They include Robert Santiago, Xavier Dutoit, Joe Murray, Sarmeesha 
Reddy, Jay Maechtlen, Dream Gomez, Leila Johnson, Duncan Hutty, and Kurundjalmi. 




Our office for the week was Dave and Bob's house. 
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We mitigated the hardship of late-night work with some tasty beverages. 




And occasionally they let us out for a bit.. 



HOW TO CONTRIBUTE TO THIS MANUAL 



If you would like to contribute then follow these steps: 



1. REGISTER 



Register at FLOSS Manuals: 
http://en.flossmanuals.net/register 
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2. CONTRIBUTE! 

Select the manual http://en.flossmanuals.net/bin/view/CiviCRM/WebHome and a chapter to 
work on. 

If you need to ask us questions about how to contribute then join the chat room listed below 
and ask us! We look forward to your contribution! 

For more information on using FLOSS Manuals you may also wish to read our manual: 
http://en.flossmanuals.net/FLOSSManuals 

To help give our manual some continuity, we've come up with some agreed writing 
conventions . You should probably read this before contributing. 

3. CHAT 

It's a good idea to talk with us so we can help co-ordinate all contributions. We have a chat 
room embedded in the FLOSS Manuals website so you can use it in the browser. 

If you know how to use IRC you can connect to the following: 
server: irc.freenode.net 
channel: #booksprint 

4. MAILING LIST 

For discussing all things about FLOSS Manuals join our mailing list: 
http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net 
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62. 



GLOSSARY 



A|B|C|D|E|F|G|H|j|l|K|L|M|N|0|P|Q|R|S|I|U|V|W|X|Y|Z 

Bolded words in the glossary definitions indicate words or terms that have their own glossary 
entry. 

ACCIDENTAL TECHIE 

Someone who has inherited the role of IT technical support but whose primary role maybe 
something else; often has little or no formal IT training (which is not always a bad thing!). 

ACCORDION 

A javascript-based effect on a web page that allows additional content to be revealed or 
hidden (often referred to as collapsed or uncollapsed) without the user leaving the web page. 

ACL (ACCESS CONTROL LIST) 

ACLs define permissions for a group of contacts to perform an operation (e.g. edit, view, 
delete) on a set of data or a type of record. For example, you could set up a group called 
"Administrators" that allows people to view and edit all contact records, and a group called 
"Volunteers" that can view contact records but not edit them. 

ACTIVITIES 

An activity in CiviCRM is a record of any scheduled or completed interaction with one or more 
contacts. Examples include meetings, phone calls, emails, event attendances and 
contributions. You can define additional types of activities as needed. 

ADMIN / ADMINISTRATOR 

The person or persons that maintain a server or a web-based software like CiviCRM. 
Administration includes maintenance, configuration, backup, security, creating and deleting 
user accounts and so on. 

AGM (ANNUAL GENERAL MEETING) 

An AGM is a meeting held every year by an organisation to inform its members of previous 
and future activities. Certain types of organisations are required by law to hold an AGM. 

AGPL (AFFERO GENERAL PUBLIC LICENSE) 

A license for open source software. CiviCRM uses the AGPL version 3.0 license , which gives 
you the right to do with the software as you like and guarantees that the source code will 
always protect your rights in this way. 

ALPHA VERSION 

A software version that contains very new source code with new functionality and bug fixes. 
An alpha version is released for testing purposes, and for people who want to follow its 
development, but it is not considered to be any where near ready for general release or use. 
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APACHE 

The most popular web server software. Apache is free and open source (see also FLOSS). 

API (APPLICATION PROGRAMMING INTERFACE) 

An interface employed by a software application to enable interaction between itself and 
other software. 

BACKUP 

Protecting your data by regularly making copies and storing them independently of the original 
files so they can be restored if necessary. 

BANDWIDTH 

The speed at which you can transfer information through a network or internet connection. If 
a connection can transfer a lot of information it is said to be "high bandwidth". 

BETA VERSION 

A software version that is in good condition but still needs testing to make sure it functions 
as intended before general release. Testing beta versions is a helpful way to participate in the 
CiviCRM community. 

BLOG 

Short for web-log. A website which is regularly updated with news and views from one or 
more individuals. 

BUG 

An error that prevents software from behaving as the user would expect. 

BUG REPORTING / BUG FIXING 

The process of reporting bugs to the software developer(s), and then fixing the bugs so the 
software operates as intended. 

BUG TRACKER 

An official repository for recording bugs. The CiviCRM bug tracker can be found here: 
http://issues.civicrm.org/ (click on Issue Tracker). 

CACHE 

A recent copy of frequently used data that can be quickly and easily accessed. This is 
especially useful if the data is complicated or takes a large effort to generate. The 
disadvantage of caching is that data can become out of date, but this normally isn't a 
problem. Even caching data for 5 minutes might be useful in certain circumstances. If a page is 
accessed 1,000 times in 5 minutes, having a cached version means the data will only need to 
be generated once. 

A web cache holds copies of recently visited web page files. Sometimes a user may need to 
clear their web cache in order to see updated information on a web page. 
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CAPTCHA 

A spam prevention tool. See reCaptcha. 

CIVICASE 

The case management component of CiviCRM. CiviCase provides service organisations with 
tools for structuring, scheduling and recording case activities. 

CIVICONTRIBUTE 

CiviContribute is an online fundraising and donor management component which enables you 
to track and manage contributions to your organisation. 

CIVICRM 

What this whole manual is about! CiviCRM is web-based, open source software that allows 
you to record and manage information about your various constituents including volunteers, 
activists, donors, employees, clients, vendors, etc. 

CIVIDOG 

See Scout. 

CIVIEVENT 

CiviEvent provides integrated online event registration and management for paid and free 
events. 

CIVIMAIL 

CiviMail is a mass-mailing component which allows you to engage constituents with 
personalised email blasts and newsletters. 

CLIENT 

A term used sometimes instead of constituent or contact, more often in a context involving 
a financial transaction. 

Client is also a term for a system (computer) or application that accesses a remote computer 
such as a web server to receive information; examples include a personal computer that is 
connected to the internet, or an email application that downloads email from a server. 

CLOSED SOFTWARE 

Software that does not allow users to access its source code, as opposed to open source 
software. See also proprietary software. 

CMS (CONTENT MANAGEMENT SYSTEM) 

An application used to create, edit, manage, search and publish various kinds of digital content 
(text and other media such as images and videos). Web-based CMS allow organisations to add 
and manage content on their website without requiring advanced technical skills. CiviCRM is 
often integrated with a CMS (commonly Drupal or Joomla!) which helps to facilitate client 
interaction. 
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COMPONENT 

A part of a CMS or other application that can be enabled or disabled, according to the needs 
of the user. Examples include CiviEvent or CiviCase. See also module. 

COMMUNITY ADVISORY GROUP 

A representative group of people from the CiviCRM community who work with the CiviCRM 
team on project development. 

COOKIE 

A file stored on your computer and used by a website to identify you on return visits. Some 
websites cannot be accessed unless you allow your computer to accept and store cookies. 

CONSTITUENT 

A constituency is usually defined as a group of people bound by shared identity, goals, or 
loyalty. In CiviCRM, "constituents" is used to a describe all supporters, current or potential, of 
a given organisation. See also contact and client. 

CONTACT 

In CiviCRM a contact is either an individual, an organisation or a household about whom 
information is stored in the database. See also constituent and client. 

CONTACT SUMMARY SCREEN 

A page that displays at a glance all the data about an individual, organisation or household that 
is stored in the CiviCRM database. 

CORE CODE 

The source code that constitutes the official code of CiviCRM. Also called core. 

CORE DATA FIELD 

A field that is included in a record structure "out-of-the-box". For example, the CiviCRM 
contact record includes First Name as a core field. 

CORE TEAM 

The people most closely involved with CiviCRM development. 

CRM 

Acronym for Contact (or Constituent, Customer or Client) Relationship Management. CRM (or 
eCRM) software was originally developed from a sales perspective, to help companies track 
and organise their interactions with current and potential customers. CiviCRM is oriented 
specifically toward the needs of non-profits, advocacy and non-governmental organisations, 
so the term "customer" is replaced with "constituent". Outside the USA it is often referred 
to as Contact Relationship Management. 

CRON JOB 
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A cron job is a way of automatically scheduling a programme to run at certain intervals. Crons 
are often used in CiviCRM to handle daily or monthly events such as sending membership 
renewal reminders or processing ongoing payments. 

CRUD 

Create, Read, Update and Delete: the basic functions performed on databases. 

CSS (CASCADING STYLE SHEETS) 

A way to control the style of a website by defining design and layout elements in a single file 
which is linked to all files in a website and applies the style across the site. An element, such 
as the formatting of a heading or a background colour, can be changed once in the CSS file to 
effect a change on all pages of the site. 

CSV (COMMA SEPARATED VALUES) 

A simple format for a spreadsheet. CSV files are text files where each cell is separated by a 
comma, and each row is separated with a return. This very simple format is understandable 
by many different programmes. 

CUSTOM DATA FIELD 

A field that is added to the data structure of a CiviCRM record by your organisation. Custom 
data fields extend the information that can be stored in that type of record. For example, 
your organisation might need a custom field to record each contacts' professional 
qualifications, or the food preferences of event participants. 

DASHBOARD 

A user's homepage, which displays when the user logs in to CiviCRM and which can be 
personalised with dashlets. 

DASHLET 

A report on some data in the CiviCRM database, configured to appear on a user's dashboard. 
For example, monthly figures in graph and/or numerical form, appointments for the day, or a 
list of new memberships. 

DATA CENTRALISATION 

Storing all your data in one place. 

DATABASE 
DEMO SITE 

A website that allows you to test and explore the functionality of a piece of software. 
CiviCRM maintains three demos sites: one integrated with Drupal, one integrated with 
Joomla! and one in standalone mode. 

DEDUPE 

Refers to the task of finding and merging multiple entries for one contact. 
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DEVELOPER 

Someone who develops software. 

DOMAIN 

See DNS. 

DONOR 

Someone who makes a donation, i.e. voluntarily gives money to an organisation. 

DNS (DOMAIN NAME SYSTEM) 

The Domain Name System (DNS) converts domain names, which are made up of easy-to- 
remember combinations of letters (example.com), to IP addresses (123.456.123.234) which are 
hard-to-remember strings of numbers. Every computer on the internet has an unique address 
(a little bit like an area code + telephone number). 

DRUPAL 

An open source CMS that integrates with CiviCRM to provide a user-interface and additional 
website functionality (http://drupal.org) . 

ENCRYPTION 

A way of disguising data when it is being transferred from one computer to another so that it 
is unreadable by any other computer that it may pass through on the way. 

ENVIRONMENT 

The specific hardware and operating system on which you are running your software. 

EVENT LISTING FEED 

A RSS feed containing the list of events defined in CiviEvent. 

FIREFOX 

A popular free and open source web browser, developed by the Mozilla Foundation 
(http://www.mozilla.com) 

FLOSS (FREE/LIBRE OPEN SOURCE SOFTWARE) 

Software that is licensed so as to guarantee the essential freedoms of users to its source 
code and reuse. A combination of "free software" and "open source software", with "libre" 
added in to emphasise that software freedom is essentially a matter of rights, not price. 

FOSS 

Free and Open Source Software - see FLOSS. 

FORUM 
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A web-based online discussion tool (see http://forum, civicrm.org/) , 

FREE SOFTWARE 

Software that is licensed so that you can use and distribute it without restriction. CiviCRM is 
free software. See also FLOSS. 

FTP (FILE TRANSFER PROTOCOL) 

The FTP protocol is used for file transfers from one computer to another over the internet. 
Many people use it for downloads, and it can also be used to upload files to web servers. A 
popular free and open source FTP client for Windows is FileZilla. There are also web-based 
FTP clients that you can use with a normal web browser like Firefox. 

FUNCTIONALITY 

The set of tasks that a piece of software can perform. 

GEOCODING 

The process of finding associated geographic coordinates (often expressed as latitude and 
longitude) from other geographic data, such as street addresses, or zip codes (postal codes). 

GUI (GRAPHICAL USER INTERFACE) 

User interface offering windows, icons, mouse control, multiple fonts, and so on - the normal 
way for non-programmers to communicate with their computers. The alternative to a GUI is a 
command line interface with text only. 

HOOK 

[needs definition] 

HOSTING SERVICE 

A service (usually commercial) that provides server space for your website. Hosting services 
also can provide physical space to put your own server in so that it is connected to the 
internet. 

ICT 

Acronym for Information and Communication Technology. 

INTERNATIONALISATION: I8N 

The process of making software ready for adoption in different countries and different 
cultures, without the need to modify it technically. This is done by the developer (software 
engineer) when writing the software. See also Localisation. 

INTERNET SERVICE PROVIDER (ISP) 

A business that provides services such as internet access, email, and website hosting. 

INTRANET 
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A network of computers that are connected within a home or office but not accessible from 
outside the local network. 

IT 

Acronym for Information Technology. 

JAVASACRIPT 

A scripting language primarily used in web pages to display dynamic content. 

JOOMLA! 

A CMS that can integrate with CiviCRM to provide a user interface and additional website 
functionality (http://www.ioomla.org ). 

LAMP 
LINUX 

A type of operating system (other common operating systems are Windows and Mac OS). 
Linux has been popular as a web server for a long time and is now gaining popularity on 
personal laptops and desktop computers. Linux is free software and open source. 

LOCAL COMPUTER 

A computer that runs CiviCRM but is not publicly available via the internet. This could be your 
personal or home computer, or it can be in your office. It can also be called a client computer 
in the context of receiving information from a server. 

LOCALISATION: LION 

The process of translating a product into different languages or adapting a language for a 
specific country or region. This is done by translators with no need for technical wizardry. 

MAIL SERVER 

A computer that transfers email from one computer to another. 

MAPPING PROVIDER 

A service provider that allows displaying contact locations on maps - Google Maps or Yahoo 
Maps in CiviCRM. 

MAMPP 
MODULE 

A part of a system, also called a component. CiviCRM includes a number of modules, each of 
which adds functionality to the basic contact management features. For example, the 
CiviEvent module provides event management functionality. Organisations using CiviCRM can 
turn modules on or off, according to their needs. 

MYSQL 
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A popular database engine. CiviCRM uses MySQL to hold its data. MySQL is free software. 

(http://mysql.com) 

NGO (NON-GOVERNMENTAL ORGANISATION) 

A legally constituted non-business organisation with no participation or representation from 
government. In the United States, this type of organisation is more often referred to as a 
Non-profit. They may be also called civil society organisations or not-for-profits. 

NON-PROFIT 

see NGO. 

NUMERONYM 

A word where a number is used to form an abbreviation. For example, localisation and 
internationalisation (referring to the translation of software and web pages) are often 
written as L10n and i18n, with the numbers denoting how many letters have been skipped. 

ONLINE CONTRIBUTION PAGE 

A function of CiviCRM which allows the creation of a page on the website where visitors can 
make online donations using credit cards. 

OPEN ID 

A convenient free system to use a single digital identity across the internet. 

OPEN SOURCE SOFTWARE 

Software with source code that is publicly available, as opposed to proprietary software; 
see also FLOSS. Open source software is based on the philosophy that sharing and 
collaborating on code leads to better software and greater benefit for everyone. 

PAYMENT INSTRUMENT 

Medium or method that is used for online payments. 

PAYMENT PROCESSOR 

A company (usually a third party) appointed by a merchant to handle credit card transactions 
for merchant banks. A payment processor is required to handle online transactions through a 
system such as CiviCRM. 

PERMISSIONS 

Allow you to limit access for different users to different parts of the system. 

PERSONAL CAMPAIGN PAGES 

A feature of CiviCRM that can be enable to allow constituents to create their own 
fundraising pages. 

PHP 
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The programming language in which the majority of CiviCRM is written. 

PING 

Sending and receiving small amounts of data to and from a server; often used to measure 
the response time across the network. 

POINT PERSON 

Someone given the responsibility to keep their eye on a certain issue. 

PREMIUM 

A gift that can be offered to contributor in exchange for donation. CiviCRM allows offering 
premiums as a part of the donation gathering process. 

PRICE SETS 

A way of storing and re-using complicated price structures for events. For example, you can 
charge for different elements of an event. 

PRIMARY LOCATION 

The information that a constinutent wants to be used as their main point of contact for 
mailings etc. 

PROFILES 

A central concept in CiviCRM. In essence a subset of fields. See the chapter on Collecting 
and Sharing Data for a full explanation. 

PROPRIETARY SOFTWARE 

Also called closed software or closed source software. Software licensed so that you cannot 
access the source code and modify it without first coming to an agreement with the authors. 
See also open source software. 

PROTOCOL 

An agreed-upon method of doing something. HTTP and SMTP are two examples, one being an 
agreement on how to transfer website data across the web, the other an agreement on how 
email will be transferred across the web. 

RADIO BUTTON 

An element of a web-based application user interface that allows the user to choose only one 
of a predefined set of options. Usually indicated by a white circle that can be filled with a click. 

RECAPTCHA 

A common tool for testing whether a user is a human or a computer, used to prevent spam. 

REQUIREMENTS 
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The things that you require a particular software application to do. 

RICH TEXT EDITOR 

A text editor that allows you to add formatting, such as bold, italic and underline, to text (as 
opposed to just plain text). 

ROOT DOMAIN 

The 'raw' URL of a website without 'www' or any other subdomain. For example, 
http://civicrm.org/ is the root domain while http://www.civicrm.org/ is not. 

RSS (REALLY SIMPLE SYNDICATION) FEED 

RSS feeds are a way to publish frequently updated information, either for inclusion on a 
website or to be read by an RSS reader. 

RSVP 

"Repondez s'il vous plait", a French phrase that translates to "please respond". Commonly 
used to request confirmation (or declining) of attendance at an event. 

SCRIPT 

A script is a short programme that does one specific task. Many web pages include scripts to 
manage user interaction, so that the server does not have to send a new page for each 
change. 

SCOUT 

The CiviCRM Book Sprint official dog. Scout likes dog biscuits, rolling on the ground, eating 
snow and proof-reading. 

SENDMAIL 

Sendmail is one of the most popular mail transfer agents (MTA) used for handling email on a 
server. Sendmail is free and open source software. 

SERVER 

1. Software that "serves" content to a client. See Apache, or Mail Server for two examples. 

2. A computer that is used primarily to serve content. Any computer can be set up this way, 
but the term traditionally refers to those that deliver web content. See also client computer. 

SHARED HOSTING 

A website hosting service, where multiple websites reside on single server. 

SMART GROUP 

A group in CiviCRM to which contacts are automatically assigned. Smart groups are created 
by running and then saving a search. They are useful for groups that might change frequently, 
for example "donations over $1000 in the last month". 
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SMTP 

Simple Mail Transfer Protocol. A standard or protocol used by email software to transfer 
(send) email. 

SOFT CREDIT 

Allows you to credit a contact for a donation made by someone, for example the person who 
inspired the actual donor to make a donation. See Personal Campaign Pages. 

SOFTWARE 

Applications (also called programs or programmes) that enable specific functionality on your 
computer. There are many broad categories of software such as web browsers, word 
processors and email clients. Within each category there are many available softwares that 
perform the functions you require. For example, Firefox and Internet Explorer are two 
commonly-used web browsers. 

SOFTWARE LICENSE 

The terms you must accept before using a piece of software. 

SOURCE CODE 

Software is created by writing instructions that a computer understands. These lines of 
instructions are known as code or source code. 

SSL (SECURE SOCKETS LAYER) 

One way of making internet communication secure. You can easily see if you are using SSL by 
looking at the URL in your browser: if it starts with https instead of http, your connection is 
using SSL. 

SSL CERTIFICATE 

Provided by the server to prove its identity, in the same way that a person carries a passport 
or driving license. See also SSL (Secure Sockets Layer). 

STABLE VERSION 

A version of software that has been tested and is considered to be ready for general use. 

STANDALONE 

An installation of CiviCRM which is not integrated with a CMS such as Drupal or Joomla!. 

STRING 

A string is a sequence of characters for example "Hello, World", the URL 
" http://www.flossmanuals.net/ " or the text message "No such file or directory". Different 
character sets allow different strings. Unicode strings can include any combination of 
languages, such as "Japan (02^) and Korea ( t }!S!: , ?l^")". 

SUBDOMAIN 
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A domain that is a part of larger larger domain. For example: en.flossmanuals.net and 
fa.flossmanuals.net are subdomains of the domain flossmanuals.net. 

TOKEN 

Tokens are used in CiviCRM to insert elements such as a contact's name or a standard 
greeting into emails being sent from the system. In an email sent to a group of people, the 
token {first. name} will be replaced with actual name of each message recipient, in the email 
that each individual receives. 

UPGRADE 

The process of replacing software with a newer version of the same software. An upgrade 
may fix bugs, improve security, enable the software to continue to work with upgraded 
operating systems, or provide new features and other enhancements. 

URL 

Acronym for Unique Resource Locator, sometimes referred to as a Universal Resource 
Indicator, or URI. The technical convention that identifies the location of a resource on a 
network. The resource might be a web page, in which case the URL refers to the location of 
that web page on the internet, for example www.civicrm.org is the URL for CiviCRM. 

USE CASE 

Use case is a central concept in software development. A use case is a story or scenario that 
documents the experience of performing a specific task with the application. Generally, a use 
case should avoid technical or database-specific language, such as 'fields' or 'record', and 
concentrate on real world objects and scenarios in order to communicate the idea clearly to 
people who may not be familiar with technical terms. 

VERSION 

Updates to software are released periodically, and these releases are referred to as a version 
of the software. There are different types of version, for example the most recent release of 
a software which has been tested and is intended for general use is referred to as the stable 
version, while a very new untested version is the alpha version. 

VPN (VIRTUAL PRIVATE NETWORK) 

A method of sharing information between members of an organisation over encrypted 
connections. 

WAMP 

WEB APPLICATION 

A software application that provides a website with additional functionality. CiviCRM is a web 
application. 

WEBMAIL 
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Webmail is email service through a website. The service sends and receives email messages 
for users in the usual way, but provides a web interface for reading and managing messages, 
as an alternative to running a mail client like Outlook Express or Thunderbird on the user's 
computer. For example a popular and free webmail service is https://mail.google.com/ 

WEB-SERVER 
WIKI 

A web-based software that enables anyone to edit content via a web browser. Wikipedia is 
the best known example of a wiki. 

WILDCARD 

A character that can match an any number and collection of characters, normally represented 
by . For example, when used in searches, ab finds ab, abba and abracadabra but not 
fabulous; ab finds fabulous. 

WORK STATION 

A computer used for working; often in a situation such as an office where there are other 
computers that may include servers. 

WYSIWYG (WHAT YOU SEE IS WHAT YOU GET) 

An application that provides a visual tool for editing web content, so that the user can see 
how the page will look in the browser as they are editing, instead of working in the HTML 
code. See also rich text editor. 

XAMPP 
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All chapters copyright of the authors (see below). Unless otherwise stated all chapters in this 
manual licensed with GNU General Public License version 2 

This documentation is free documentation; you can redistribute it and/or modify it under the 
terms of the GNU General Public License as published by the Free Software Foundation; either 
version 2 of the License, or (at your option) any later version. 

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY 
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 
PARTICULAR PURPOSE. See the GNU General Public License for more details. 

You should have received a copy of the GNU General Public License along with this 
documentation; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth 
Floor, Boston, MA 02110-1301, USA. 
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1 MANUA1S 

Free manuals for free software 

GENERAL PUBLIC LICENSE 

Version 2, June 1991 

Copyright (C) 1989, 1991 Free Software Foundation, Inc. 
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA 

Everyone is permitted to copy and distribute verbatim copies 
of this license document, but changing it is not allowed. 

Preamble 

The licenses for most software are designed to take away your freedom to share and change 
it. By contrast, the GNU General Public License is intended to guarantee your freedom to 
share and change free software—to make sure the software is free for all its users. This 
General Public License applies to most of the Free Software Foundation's software and to any 
other program whose authors commit to using it. (Some other Free Software Foundation 
software is covered by the GNU Lesser General Public License instead.) You can apply it to 
your programs, too. 

When we speak of free software, we are referring to freedom, not price. Our General Public 
Licenses are designed to make sure that you have the freedom to distribute copies of free 
software (and charge for this service if you wish), that you receive source code or can get it if 
you want it, that you can change the software or use pieces of it in new free programs; and 
that you know you can do these things. 

To protect your rights, we need to make restrictions that forbid anyone to deny you these 
rights or to ask you to surrender the rights. These restrictions translate to certain 
responsibilities for you if you distribute copies of the software, or if you modify it. 
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For example, if you distribute copies of such a program, whether gratis or for a fee, you must 
give the recipients all the rights that you have. You must make sure that they, too, receive or 
can get the source code. And you must show them these terms so they know their rights. 

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license 
which gives you legal permission to copy, distribute and/or modify the software. 

Also, for each author's protection and ours, we want to make certain that everyone 
understands that there is no warranty for this free software. If the software is modified by 
someone else and passed on, we want its recipients to know that what they have is not the 
original, so that any problems introduced by others will not reflect on the original authors' 
reputations. 

Finally, any free program is threatened constantly by software patents. We wish to avoid the 
danger that redistributors of a free program will individually obtain patent licenses, in effect 
making the program proprietary. To prevent this, we have made it clear that any patent must 
be licensed for everyone's free use or not licensed at all. 

The precise terms and conditions for copying, distribution and modification follow. 

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 

0. This License applies to any program or other work which contains a notice placed by the 
copyright holder saying it may be distributed under the terms of this General Public License. 
The "Program", below, refers to any such program or work, and a "work based on the 
Program" means either the Program or any derivative work under copyright law: that is to 
say, a work containing the Program or a portion of it, either verbatim or with modifications 
and/or translated into another language. (Hereinafter, translation is included without limitation 
in the term "modification".) Each licensee is addressed as "you". 

Activities other than copying, distribution and modification are not covered by this License; 
they are outside its scope. The act of running the Program is not restricted, and the output 
from the Program is covered only if its contents constitute a work based on the Program 
(independent of having been made by running the Program). Whether that is true depends on 
what the Program does. 

1. You may copy and distribute verbatim copies of the Program's source code as you receive 
it, in any medium, provided that you conspicuously and appropriately publish on each copy an 
appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer 
to this License and to the absence of any warranty; and give any other recipients of the 
Program a copy of this License along with the Program. 

You may charge a fee for the physical act of transferring a copy, and you may at your option 
offer warranty protection in exchange for a fee. 

2. You may modify your copy or copies of the Program or any portion of it, thus forming a 
work based on the Program, and copy and distribute such modifications or work under the 
terms of Section 1 above, provided that you also meet all of these conditions: 

a) You must cause the modified files to carry prominent notices stating that you 
changed the files and the date of any change. 

b) You must cause any work that you distribute or publish, that in whole or in part 
contains or is derived from the Program or any part thereof, to be licensed as a whole 
at no charge to all third parties under the terms of this License. 

c) If the modified program normally reads commands interactively when run, you must 
cause it, when started running for such interactive use in the most ordinary way, to 
print or display an announcement including an appropriate copyright notice and a notice 
that there is no warranty (or else, saying that you provide a warranty) and that users 
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may redistribute the program under these conditions, and telling the user how to view a 
copy of this License. (Exception: if the Program itself is interactive but does not 
normally print such an announcement, your work based on the Program is not required 
to print an announcement.) 

These requirements apply to the modified work as a whole. If identifiable sections of that 
work are not derived from the Program, and can be reasonably considered independent and 
separate works in themselves, then this License, and its terms, do not apply to those sections 
when you distribute them as separate works. But when you distribute the same sections as 
part of a whole which is a work based on the Program, the distribution of the whole must be 
on the terms of this License, whose permissions for other licensees extend to the entire 
whole, and thus to each and every part regardless of who wrote it. 

Thus, it is not the intent of this section to claim rights or contest your rights to work written 
entirely by you; rather, the intent is to exercise the right to control the distribution of 
derivative or collective works based on the Program. 

In addition, mere aggregation of another work not based on the Program with the Program (or 
with a work based on the Program) on a volume of a storage or distribution medium does not 
bring the other work under the scope of this License. 

3. You may copy and distribute the Program (or a work based on it, under Section 2) in object 
code or executable form under the terms of Sections 1 and 2 above provided that you also do 
one of the following: 



a) Accompany it with the complete corresponding machine-readable source code, which 
must be distributed under the terms of Sections 1 and 2 above on a medium customarily 
used for software interchange; or, 

b) Accompany it with a written offer, valid for at least three years, to give any third 
party, for a charge no more than your cost of physically performing source distribution, 
a complete machine-readable copy of the corresponding source code, to be distributed 
under the terms of Sections 1 and 2 above on a medium customarily used for software 
interchange; or, 

c) Accompany it with the information you received as to the offer to distribute 
corresponding source code. (This alternative is allowed only for noncommercial 
distribution and only if you received the program in object code or executable form with 
such an offer, in accord with Subsection b above.) 

The source code for a work means the preferred form of the work for making modifications 
to it. For an executable work, complete source code means all the source code for all modules 
it contains, plus any associated interface definition files, plus the scripts used to control 
compilation and installation of the executable. However, as a special exception, the source 
code distributed need not include anything that is normally distributed (in either source or 
binary form) with the major components (compiler, kernel, and so on) of the operating system 
on which the executable runs, unless that component itself accompanies the executable. 

If distribution of executable or object code is made by offering access to copy from a 
designated place, then offering equivalent access to copy the source code from the same 
place counts as distribution of the source code, even though third parties are not compelled to 
copy the source along with the object code. 

4. You may not copy, modify, sublicense, or distribute the Program except as expressly 
provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute 
the Program is void, and will automatically terminate your rights under this License. However, 
parties who have received copies, or rights, from you under this License will not have their 
licenses terminated so long as such parties remain in full compliance. 
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5. You are not required to accept this License, since you have not signed it. However, nothing 
else grants you permission to modify or distribute the Program or its derivative works. These 
actions are prohibited by law if you do not accept this License. Therefore, by modifying or 
distributing the Program (or any work based on the Program), you indicate your acceptance of 
this License to do so, and all its terms and conditions for copying, distributing or modifying the 
Program or works based on it. 

6. Each time you redistribute the Program (or any work based on the Program), the recipient 
automatically receives a license from the original licensor to copy, distribute or modify the 
Program subject to these terms and conditions. You may not impose any further restrictions 
on the recipients' exercise of the rights granted herein. You are not responsible for enforcing 
compliance by third parties to this License. 

7. If, as a consequence of a court judgment or allegation of patent infringement or for any 
other reason (not limited to patent issues), conditions are imposed on you (whether by court 
order, agreement or otherwise) that contradict the conditions of this License, they do not 
excuse you from the conditions of this License. If you cannot distribute so as to satisfy 
simultaneously your obligations under this License and any other pertinent obligations, then as 
a consequence you may not distribute the Program at all. For example, if a patent license 
would not permit royalty-free redistribution of the Program by all those who receive copies 
directly or indirectly through you, then the only way you could satisfy both it and this License 
would be to refrain entirely from distribution of the Program. 

If any portion of this section is held invalid or unenforceable under any particular 
circumstance, the balance of the section is intended to apply and the section as a whole is 
intended to apply in other circumstances. 

It is not the purpose of this section to induce you to infringe any patents or other property 
right claims or to contest validity of any such claims; this section has the sole purpose of 
protecting the integrity of the free software distribution system, which is implemented by 
public license practices. Many people have made generous contributions to the wide range of 
software distributed through that system in reliance on consistent application of that system; 
it is up to the author/donor to decide if he or she is willing to distribute software through any 
other system and a licensee cannot impose that choice. 

This section is intended to make thoroughly clear what is believed to be a consequence of the 
rest of this License. 

8. If the distribution and/or use of the Program is restricted in certain countries either by 
patents or by copyrighted interfaces, the original copyright holder who places the Program 
under this License may add an explicit geographical distribution limitation excluding those 
countries, so that distribution is permitted only in or among countries not thus excluded. In 
such case, this License incorporates the limitation as if written in the body of this License. 

9. The Free Software Foundation may publish revised and/or new versions of the General 
Public License from time to time. Such new versions will be similar in spirit to the present 
version, but may differ in detail to address new problems or concerns. 

Each version is given a distinguishing version number. If the Program specifies a version 
number of this License which applies to it and "any later version", you have the option of 
following the terms and conditions either of that version or of any later version published by 
the Free Software Foundation. If the Program does not specify a version number of this 
License, you may choose any version ever published by the Free Software Foundation. 

10. If you wish to incorporate parts of the Program into other free programs whose 
distribution conditions are different, write to the author to ask for permission. For software 
which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; 
we sometimes make exceptions for this. Our decision will be guided by the two goals of 
preserving the free status of all derivatives of our free software and of promoting the sharing 
and reuse of software generally. 



293 



NO WARRANTY 

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE 
PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE 
STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE 
PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, 
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 
FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND 
PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, 
YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL 
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE 
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR 
INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA 
BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A 
FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH 
HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 

END OF TERMS AND CONDITIONS 



294 



Thanks for reading! 

Visit http://flossmanuals.net to make corrections or to find more manuals. 



